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PREFACE

The Apple II Reference Manual contains a complete assembly listing of
the Monitor program in the Apple II. The Apple II Monitors Peeled
Manual (this book) contains descriptions of the various routines in
the Monitor and address tables arranged by topic instead of in the
sequence of location within the machine. The material you find here
has been chosen and organized to allow programmers of the Apple II to
make convenient use of routines in the Monitor from their programs.

Many of the CALLable points in the Monitor fall under more than one
topic. The layout of this book is intended to minimize the
necessity of page flipping and cross referencing, so those points
which seem to be appropriately described under more than one topic
will be found in each applicable table.

This document covers the Apple II Monitor (both the Old Monitor and
the Autostart Monitor versions), ROM address range $F800-$FFFF. This
publication does not cover BASIC, APPLESOFT, DOS, HIRES, SWEET16, or
Floating Point Arithmetic utility routines.

INTRODUCTION

There are two Monitor ROM’s available for the Apple II. The two
Monitors are identical for most functions. They differ only in certain
features. This book describes both Monitors, with indications provided
whenever the information applies to only one of the two.

Some thousands of Apple II computers have been shipped with the
earlier version of the Monitor. In this book, that will be referred
to as the Old Monitor. In 1979, a new version of the Apple II Monitor
was developed. This Monitor contains new features to facilitate system
start-up and program editing, at the expense of removing the
instruction trace and single step facilities and sixteen bit multiply-
divide routine of the Old Monitor. This new Monitor is called the
Autostart Monitor in this book, The Autostart Monitor is available
from Apple Computer Inc. and from many computer dealers under the
name Autostart ROM, Apple Part No. A2H0027.

It is easy to determine which Monitor is in a machine, If the machine
comes up with the APPLE II legend at the top of the screen when the
power is turned on, the machine contains the Autostart Monitor. If the
machine comes up with the Monitor prompt(*) then it contains the Old
Monitor.

A program can also determine whether the Monitor is the Old or the
Autostart ROM, The byte at $FAFF (64255 or -1281) contains $00 in the
Autostart and $01 in the Old Monitor.

OVERVIEW
	
CHAPTER 1

MONITOR USAGE MEMORY MAP
     Use of memory by the Monitor and by the Apple II for machine
     control and display to the screen.

PAGE ZERO
     Description in detail of all memory locations in page zero used
     by the Monitor, indicating legal range of values and all routines
     which use the location.

PAGES ONE THROUGH THREE
     General descriptions of pages one and two and specific
     description of fields in page three.

PAGES FOUR THROUGH SEVEN AND ELEVEN
     Description of how text is maintained in “screen refresh memory”
     for display on the screen, both primary and secondary display
     areas for text and Low Resolution (Color) graphics.

PERIPHERAL CONTROLLER WORK AREAS
     A chart showing the scratchpad areas available in RAM memory for
     use by peripheral controller programs.

CHAPTER 2

KEYBOARD INPUT DIVISION OF LABOR
     Descriptions of the lower level routines used by the Monitor to
     read data from the keyboard, including subroutines for cursor
     movement without reading characters.

USER CALLS TO KEYBOARD INPUT ROUTINES
     Specifications for user calling of the routines at all levels for
     input of characters from the keyboard and for user program
     simulating (replacing) the keyboard as the input device.

KEYBOARD INPUT HONITOR ROUTINE
     Table 1 contains addresses for character by character input from
     the keyboard via the routines described in the previous section.
     Table 2 contains addresses for line input from the keyboard.

OVERVIEW - TEXT OUTPUT TO THE SCREEN
     Because there are so many ways to write text to the screen, this
     section contains an overview of the following pages on screen output.

TEXT OUTPUT WITHIN THE SCROLL WINDOW
     Detailed description of the normal method of printing data to the
     screen, as used by PRINT of BASIC, including page zero reference
     table for Scroll Window services.

SCREEN FORMAT CONTROL BY ROUTINE
     Table of addresses of routines in the Monitor which control the
     format of the Scroll Window and the format of data display.

SCREEN FORMAT CONTROL BY POKE/STORE
     Description of methods of controlling the screen display format
     without calling routines in the Monitor.

SCROLL WINDOW DATA MANIPULATIONS
     Table of routines which affect the data displayed in the Scroll
     Window, such as clearing part of it or scrolling it.

CURSOR POSITION CONTROL
     Description of facilities for moving the cursor relative to
     current position or to an absolute location.

GENERAL TEXT TO THE SCREEN
     Printing data to the screen whether some other device has been
     established (via CSWL) or not, and printing some things by a call
     to a Monitor routine which loads the A-reg and calls COUT itself.

TEXT OUTPUT WITHOUT THE SCROLL WINDOW
     Ways and means of handling the screen as a formatted display
     device, with or without part of the screen being defined as a
     Scroll Window.

SECONDARY DISPLAY AREAS
     Different methods of getting data into the secondary text display
     area.

CHAPTER 3

OVERVIEW OF INTERRUPT PROCESSING
     General and specific definition of interrupts and interrupt
     processing with regard to computers in general and the Apple II
     in particular.

RESET INTERRUPT - OLD MONITOR
     Description of handling a RESET interrupt with address table
     allowing user call to subsets.

RESET INTERRUPT - AUTOSTART MONITOR
     Description of handling a RESET interrupt with address table
     allowing user call to subsets. Description of Soft Entry Vector
     setup and use.

IRQ/BRK INTERRUPT HANDLING
     Descriptions of handling these types of interrupts by both
     Monitors, with Address Tables.

CHAPTER 4

MACHINE LANGUAGE DEVELOPMENT AIDS
     Address table for routines in the Monitor which can be called to
     provide debugging information either by moving the information to
     some other place in memory or printing information through COUT.

LORES PLOTTING
     Descriptions of the routines in the Monitor which support this
     function, with a table of addresses for directly calling them.

DATA MANIPULATION FUNCTIONS
     Description of the routines in the Monitor which move data from
     one place to another, or change the format, or operate on one
     item with regard to another.

MONITOR COMMAND PROCESSOR
     How to call the Monitor Command Processor, to have it execute
     Monitor commands and return to caller or stay in Monitor mode.

SPEAKER (BELL) USE THROUGH THE MONITOR
     No music here. This is a description of how to use the speaker as
     a signaling device in the same manner as the error alarm or RESET
     key alarm.

CASSETTE TAPE INPUT AND OUTPUT
     Description of all the routines involved with reading or writing
     of tape, with user call information specified for the high level
     routines. Includes list of calling programs for each point.

PADDLES, BUTTONS, AND ANNUNCIATOR I/0
     Description of paddle reading for the machine language programmer
     and addresses to use for all these devices.

WAIT ROUTINE
     This routine will take control of the machine for a length of
     time depending upon the input A-reg value. Table and formula are
     provided for use where interval between events is critical.

USE OF CONTROL-Y WITH PARAMETERS
     Sample machine language program for rapid reading of the
     paddles.

REGISTERS FOR BASIC MONITOR CALLS
     The Monitor GO command routine makes it possible to call from
     BASIC most Monitor routines which receive input in registers.

DECIMAL TO HEX CONVERSION
     A sample program that shows how to convert from decimal to
     hexadecimal.

STEP AND TRACE PECULIARITIES
     Differences between operation of the machine with and without
     Single Step in the Old Monitor.

CHAPTER 1

MEMORY ALLOCATION

MONITOR USAGE MEMORY MAP	

Memory is divided into 256 byte sections, generally referred to as
“pages”. As with most countable items in computers, memory pages are
numbered from zero. Page zero is very special in that the full
address of a byte in page zero may be expressed in a single byte.
Many 6502 processor instructions are only two bytes in length because
the operand is in page zero, Thus, Monitor usage of page zero
receives heavy treatment in the following section.

Page one (address range $0100-$01FF) is also special in the Apple II,
This entire 256 byte area is called the “stack”. The stack is a
temporary storage area for which special instructions are provided in
the 6502. The contents of the A-register or P-register may be pushed
onto the stack, which means the contents of the indicated register
are stored in the stack at the location currently specified by the
S-register: then the S-register is decremented. Data may be pulled or
popped from the stack, which means that the S-register is
incremented, and then the byte pointed at by the S-register is picked
up into the appropriate register. A JSR instruction causes the
current contents of the Program Counter to be pushed onto the stack
before the jump. An RTS instruction pulls two bytes from the stack
into the Program Counter.

The Monitor contains instructions which use the stack. However, the
Monitor does not initialize the stack pointer register to a preset
value or load the S-reg at any time.

Page two (address range $0200-$02FF) is defined in the Apple II as the
keyboard input area, The Monitor routines which support reading of
the keyboard store the information into page two for use by the
calling program after the next carriage return is detected.

Page three is address range $0300-$03FF. Most of this area is unused
by the Monitor. Quite often the first 200 or so bytes are used for
machine language programs called by APPLESOFT or BASIC programs. The
Monitor uses only the last 16 bytes, as described in the Page Three
Address Table, (Note, however, that DOS uses the 32 bytes before the
Monitor’s 16.)

Pages four through seven comprise the primary text or color graphics
display area. Pages eight thru eleven comprise the secondary text or
color graphics display area when that feature of the Apple II is
used. However, page eight is generally the first page of the user
area, In the address table, pages four thru seven and eight through
eleven are described together when specifying memory address per
screen line.

From address $0800 to the end of memory in the machine is the user
area for programs and data. However, if High Resolution Graphics is
in use, then memory area from $2000 through $3FFF is the primary
display area for that function and $4000 through $5FFF may be used as
the secondary display area for that function.

RAM MEMORY ALLOCATION BY ADDRESS
  
  +--------------------------------------------------------------+
  |0000 |Page zero                                               |
  |00FF |                                                        |
  +--------------------------------------------------------------+
  |0100 |Stack                                                   |
  |01FF |                                                        |
  +--------------------------------------------------------------+
  |0200 |Keyboard Input                                          |
  |02FF |                                                        |
  +--------------------------------------------------------------+
  |0300 |Available                                               |
  |03CF |                                                        |
  |03D0 |DOS                                                     |
  |03EF |                                                        |
  |03F0 |Vectors                                                 |
  |03FF |                                                        |
  +--------------------------------------------------------------+
  |0400 |Primary Text                                            |
  |07FF |and LORES Area                                          |
  +-----------------------+------------------+-------------------+
  |0800 |User Program     | Secondary Text   |   RAM APPLESOFT   |
  |     |and Data space   | and LORES        |   COMPILER/       |
  |0BFF |to RAM size.     |                  |    INTERPRETER    |
  |     |                 +------------------+                   |
  |     |ROM APPLESOFT    |                  |                   |
  |     |USER PROGRAM     +------------------+                   |
  |2000 |                 |Primary HIRES     |                   |
  |     |INTEGER          |                  |                   |
  |2FFF |BASIC DATA       |                  |                   |
  |     |                 |                  +-------------------+
  |3FFF |                 +------------------+ RAM APPLESOFT     |
  |     |                 |Secondary HIRES   | USER PROGRAM      |
  |4000 |                 |                  |                   |
  |     |                 |                  |                   |
  |5FFF |                 |                  |                   |
  |     |                 +------------------+                   |
  |     |                                                        |
  |3FFF -end 16K machine                                         |
  |     |                                                        |
  |7FFF -end 32K machine                                         |
  |     |                                                        |
  |BFFF -end 48K machine                                         |
  +--------------------------------------------------------------+

PAGE ZERO

The Monitor makes use of the page zero locations from 32 ($20) through
73 ($49) for general functions and normal operations. Locations 74-77
($4A-4D) are not touched by the Monitor. Locations 78-79 ($4E-4F) are
modified as described below to provide a random number starting point
for an application program.

In addition, the Old Monitor uses locations 80-85 ($50-55) for the 16
bit Multiply and Divide routines (which are available for problem
program use but are not used by any other part of the Monitor). These
locations are not used by the Autostart Monitor.

The Autostart Monitor uses locations 0 and 1 during system
initialization. This initialization is described in the section on
“RESET Interrupt - Autostart Monitor” and below in describing the use
of locations 0 and 1.

PAGE ZERO FIELDS

Dec  Hex   Monitor
Addr Addr  Label    Description

00   $00   LOC0     These locations are used by the Autostart Monitor

01   $01   LOCl     during the automatic Disk Bootstrap function which
                    takes place when the computer is powered up. Using
                    these locations for indirect addressing, the slot
                    addresses are checked - from slot 7 down thru
                    slot 1 - to determine presence of a disk controller.
                    If one is found, a Jump Indirect via $00-01 is
                    executed to initiate the bootstrap operation.

32   $20   WNDLFT   Left column of the Scroll Window:
                    Range is 0 to 39 ($27).
                    This field is used only in VTABZ which sets BASL,H
                    to the memory location corresponding to CV and
                    WNDLFT. The contents, when changed by user
                    program, become effective on the next scroll
                    operation, clear to end of page op eration, or
                    carriage return output. CH contains cursor
                    horizontal position relative to (WNDLFT).

                    After changing the contents of WNDLFT, either CALL
                    VTAB or print a carriage return to the screen to
                    make it take effect.

33   $21   WNDWDTH  Width of the Scroll Window:
                    Range is 1 to 40 -(WNDLFT).
                    When a character is written through COUT to the
                    screen it is placed at (BASL),(CH), after which CH
                    is incremented. Then (CH) is compared with
                    (WNDWDTH) to determine whether the cursor has
                    exceeded the right margin of the Scroll Window.

Dec  Hex   Monitor
Addr Addr  Label    Description

34   $22   WNDTOP   Top line of the Scroll Window:
                    Range is 0 to 22 ($16) for full text screen.
                    Range is 20 to 22 ($14 and $15) for mixed graphics
                    and text.
                    Valid values for VTAB in Basics are 21, 22, 23.
                    This field is used during a scroll operation to
                    indicate the line on which the operation should
                    start. It is also the line on which the cursor is
                    placed on completion of a HOME operation (clear
                    the window, place cursor at top left).

35   $23   WNDBTM   Nominally, bottom line of Scroll Window:
                    Range is (WNDTOP)+l to 24 ($18).
                    WNDBTM contains the number of the first line below
                    the Scroll Window. Contents of WNDBTM are tested
                    only on output of a carriage return ($8D) or line
                    feed ($8A). It is used by Clear to End of Page and
                    by Scroll routines.

36   $24   CH       Displacement from WNDLFT where next character to
                    the screen will be placed: Range is 0 to
                    (WNDWDTH) - 1. After the screen output routine
                    STOADV places a character into the screen area as
                    part of normal character output, CH is then
                    incremented and compared to WNDWDTH. If CH is not
                    less than WNDWDTH, a carriage return will be
                    simulated.

                    Note that CH is used for echoing keyboard input to
                    the screen by the Monitor GETLN etc, routines.

37   $25   CV       Vertical screen position (line number) for next
                    character to be written to the screen: Range is 0
                    to 23 ($17). The content of CV is relative to the
                    top of the screen, not to the top of the Scroll
                    Window. It may be set by loading the desired line
                    number into A-reg and calling TABV. It may be set
                    by POKEing the line number into CV and then
                    calling VTAB. Actual storage of a character into
                    the screen area includes use of BASL,H for line
                    number, not CV, The calls above to VTAB or TABV
                    are to set BASL,H from CV (and WNDLFT) for
                    immediate future reference.

                    If CV is at or below WNDBTM it wi11 remain on the
                    current screen 1ine as carriage returns go by
                    while the contents of the Scroll Window will be
                    scrolled for each.

Dec  Hex   Monitor
Addr Addr  Label    Description

38   $26   GBASL    Memory address within the screen area of the left
39   $27   GBASH    end point of the desired line for LORES plot. This
                    field is set by the GBASCALC routine to the memory
                    location appropriate for the line number specified
                    in the A-reg. See MASK at $2E.

40   $28   BASL     This two byte field is the memory address for the
41   $29   BASH     left end character position of the current text line,
                    within the Scroll Window, The contents are a
                    function of CV and WNDLFT.

                    This field is set by the BASCALC routine to point
                    to the memory address for the left end of the
                    screen line specified in the A-reg. This call to
                    BASCALC is usually accomplished by the VTAB
                    routine, which then adds (WNDLFT) to BASL,H to
                    point to the left end of the line within the
                    Scroll Window.

42   $2A   BAS2L    This two byte field is used as a work area only
43   $2B   BAS2H    during a scroll operation. It is the destination
                    line pointer used as each line is moved to the
                    position above current.

44   $2C   H2       Right end point of horizontal line being drawn by
                    the HLINE routine: Range is 0 to 39 ($27).
                    This byte is set by the calling program before
                    HLINE is called.

“    “     LMNEM    Low byte of two byte pointer (LHNEM, RHNEM) used
                    by Disassembler as index to mnemonics table.

“    “     RTNL     Save area used by the Instruction Trace routine
                    of the Old Monitor.

                    Bottom point of a vertical line being drawn by
                    VLINE routine: Range is 0 to 39 ($27) for mixed
                    screen, 0 to 47 ($2F) for full screen graphics.
                    This byte must be set before VLINE is called, Note
                    that this byte is used when the Clear Screen
                    (CLRSCR) routine uses VLINE to clear the screen.

45   $2D   RMNEM    Used with LMNEM as table index for mnemonic table
                    by the Disassembler.

“    “     RTNH     Used with RTNL as a save area by the Instruction
                    Trace routine of the Old Monitor.

Dec  Hex   Monitor
Addr Addr  Label    Description

46   $2E   MASK     With this label, this location is used as a $0F
                    or $F0 by PLOT depending on whether the point is
                    on the high side or the low side of the two
                    horizontal plot lines represented by the GBASL,H
                    pointer. Each location of the form (GBASL),Y
                    contains two points on the screen, one above the
                    other. MASK is used to set the appropriate one
                    while leaving the other unchanged.

“    “     FORMAT   Using this label, the Disassembler uses this byte
                    as temporary storage for the code which indicates
                    the format of the instruction for display
                    purposes.

“    “     CHKSUM   This byte is used during cassette tape read to
                    continually accumulate the checksum which will
                    be compared to that generated during the write
                    operation which created the record. This byte is
                    initialized to zero at the beginning of a tape
                    read. As each byte is stored into memory it is
                    Exclusively ORed against CHKSUM. After the last
                    byte has been stored, one more byte is read from
                    the tape and compared to CHKSUM. If equal, a good
                    read may be assumed. As this result is not finally
                    stored back into CHKSUM, that field cannot be used
                    by the calling program to determine success or
                    failure of the read. A method for this
                    determination will be found in the section
                    “Cassette Tape Input and Output”.

47   $2F   LASTIN   With this label, the RDBIT routine uses this byte
                    as a work area to determine whether the sense of
                    input from the cassette tape input register has
                    changed.

“    “     LENGTH   This field is set by the Disassembler to indicate
                    the length of the instruction. After output of the
                    disassembled instruction, PCADJ uses this value to
                    compute new values for PCL,H, which are returned
                    to caller in the A and Y reg for user storage to
                    PCL,H. Instruction trace in the Old Monitor also
                    uses this field to indicate the number of bytes to
                    move to the instruction trace execution work area
                    (XQT).

“    “     SIGN     After a call to MULPH or DIVPH (signed 16 bit
                    multiply or divide in the Old Monitor), the $01
                    bit of this byte is set if the always-positive
                    result is to be complemented by the calling
                    program.

Dec  Hex   Monitor
Addr Addr  Label    Description

48   $30   COLOR    This byte contains the code for the color of
                    points to be placed on the screen in graphics
                    mode. The SETCOL routine is entered with a value
                    in the low order four bits of the A-reg. This
                    value is then placed in both the high and low
                    nibbles of COLOR. COLOR is then used with MASK in
                    setting the value of the byte in the screen area
                    to accomplish setting a particular point to the
                    selected color.

                    Color can be set directly by stuffing the value
                    multiplied by $11 in color. For example,
                    color = orange (9): From assembly - LDA #99,
                    STA color. From BASIC - POKE 48, 9*17.

49   $31   MODE     This byte is used by the Monitor command
                    processing routines to control parsing and to
                    control operations when a blank is encountered
                    after the hex digits. For example, a hex address
                    followed by a colon causes setting of MODE so that
                    during further processing of the input line each
                    blank encountered signifies end of a hex value to
                    be placed in memory. During parsing, the contents
                    of MODE indicate where the hex values should be
                    stored for use when the command itself is
                    encountered. MODE is set to appropriate values by
                    plus, minus, colon, and period.

50   $32   INVFLG   This byte is a mask used by COUTl to cause
                    characters written to the screen area to display
                    white on black (INVFLG=$FF) or black on white
                    (INVFLG=$3F) or blinking (INVFLG=$7F). This field
                    is set to $FF when a RESET occurs by the routine
                    at SETNORM. The routine called SETINV can be
                    called to set reverse video. The Monitor does not
                    set blinking.

51   $33   PROMPT   This byte contains the prompt character which is
                    written to the screen by the Monitor GETLN routine
                    in preparation for reading a line of characters
                    from the keyboard. When the RESET key is pressed,
                    the Old Monitor quickly enters the MON routine, at
                    which point the PROMPT field is set to $AA, “*”.
                    The Autostart monitor also sets the “*” prompt
                    character at the MON routine, but this is not
                    necessarily a part of processing the RESET
                    interrupt.

Dec  Hex   Monitor
Addr Addr  Label    Description

52   $34   YSAV     This byte is a save area used by the Monitor
                    Command Processor. The Y-reg is used by the
                    Command Processor in indexing through the input
                    line. When a command has been decoded, the Y-reg is
                    saved at YSAV before going to the selected service
                    routine. On return to the Command Processor, the
                    Y-reg is reloaded from here before transfer of
                    control to NXTITM to continue scanning the input
                    line.

53   $35   YSAV1    This byte is a save area for the Y-reg across a
                    call to the screen output routines. Y-reg is saved
                    and restored in the COUTl routine.

54   $36   CSWL     This two byte field contains the address of the
55   $37   CSWH     routine which is to receive and dispose of output
                    characters. When the RESET key is pressed this
                    field is initialized to point to COUTl to send
                    output characters to the screen. Entering a
                    Monitor Command nPc (n=port number, Pc=control-P)
                    will cause the Monitor to set CSWL to 00, CSWH to
                    Cn. The routine at that location will then receive
                    (in the A-reg) each byte “written” through COUT,
                    which is a JMP (CSWL).

                    If the Monitor Command “0Pc” is executed, CSWL,H
                    is set to point to COUTl instead of to C000.

56   $38   KSWL     This two byte field contains the address of the
57   $39   KSWH     user input routine. It is set by RESET key
                    processing to point to KEYIN which gets its input
                    from the keyboard. The Monitor Command nKc (n=port
                    number, Kc=control-K ) causes the setting of KSWL
                    to 00, KSWH to Cn. This routine is then called any
                    time the Monitor or executing program asks for
                    another byte of input by calling RDKEY or one of
                    the routines which in turn calls RDKEY.

                    The Monitor Command “0Kc” results in setting
                    KSWL,H to point to KEYIN instead of to C000.

58   $3A   PCL      This field is a save and control area for the
59   $3B   PCH      Program Counter. In addition to the Mini Assembler
                    to keep track of where the next instruction is to
                    be placed.

                    When a BRK instruction is executed, this field is
                    set to indicate the address stacked by the 6502,
                    pointing to two bytes beyond the BRK instruction
                    executed.

Dec  Hex   Monitor
Addr Addr  Label    Description

                    This field is used during Monitor commands L and G
                    (Disassembler and Monitor “GOTO”). During
                    disassembly of instructions this field is
                    incremented as required. This field is used for a
                    Jump Indirect in execution of the Monitor G
                    command.

                    Updating of this field is accomplished with the
                    assistance of the PCADJ routine whenever use
                    requires incrementing in accordance with the
                    length of the instructions. (See LENGTH at 47 or
                    $2F.) On return from PCADJ, store A to PCL and Y
                    to PCH to accomplish update.

                    This field is used by the Old Monitor in support
                    of Monitor commands S and T (single instruction
                    step and instruction trace). For those functions,
                    it is maintained as a pointer to the next
                    instruction to be handled.

60   $3C   XQT      This field is used as a work area for instruction
           XQTNZ    step and trace in the Old Monitor. The field is
61-67 $3D-$43       eight bytes long and overlays AlL,H; A2L,H; A3L,H;
                    and A4L,H. The next instruction to be executed
                    (indicated by the contents of PCL, H) is moved to
                    this field, possibly modified depending on
                    instruction type, and then executed here. This
                    field is not defined in the Autostart Monitor.

60   $3C   A1L      Multipurpose Monitor work area:
61   $3D   A1H      May be clobbered by Instruction Trace in
                    the Old Monitor; see XQT above.

                    When the Monitor begins processing a command, MODE
                    is initialized to zero. As the input line is
                    scanned, hex digits are first placed into A2L,H.
                    From there they are moved also to AlL,H and A3L,H
                    as long as MODE remains zero. When a plus, minus,
                    colon, or period is encountered, MODE is modified
                    to indicate which, and AlL,H will continue to
                    contain the value, terminated by the operator
                    encountered.

                    AlL,H is the primary index for the BLANK Monitor
                    command, memory examine or display.

                    AlL,H contains the addend for the Monitor ADD
                    command.

Dec  Hex   Monitor
Addr Addr  Label    Description

                    AlL,H contains the minuend for the Monitor
                    SUBTRACT command.

                    AlL,H is the source field pointer during the
                    Monitor MOVE command.

                    AlL,H is one of the two indices used in the
                    Monitor VERIFY command.

                    AlL,H is the source field from which PCL,H is set
                    on L and G Monitor commands, and the Old Monitor
                    commands S and T, if an address is specified. If
                    no address is used in the input line, then PCL,H
                    is the residue of the last command which
                    maintained or used it.

                    AlL,H is the memory pointer used for cassette tape
                    READ and WRITE Monitor operations.

                    Monitor routine NXTAl increments AlL,H by one and
                    then compares the result to A2L,H. If A2L,H is
                    less than AlL,H, then Carry is set when control is
                    returned to the calling program.

62   $3E   A2L      Multipurpose Monitor work area :
63   $3F   A2H      May be clobbered by Instruction Trace in
                    the Old Monitor; see XQT above.

                    This field is the receiving field into which hex
                    data is stored from the input area during Monitor
                    Command parsing. When the command itself is
                    encountered, A2L,H contains the last parameter
                    entered. While MODE contains zero (until a plus,
                    minus, colon, or period is encountered) A2L,H is
                    continually copied into AlL,H and A3L,H. If a
                    “less than” sign is encountered, A2L,H is
                    immediately copied to A4L,H and A5L,H.

                    A2L,H is used to terminate examine (memory
                    display), tape write, tape read, memory move, and
                    memory verify operations.

                    A2L,H contains the subtrahend in a Monitor
                    SUBTRACT command operation.

                    A2L,H contains the augend in a Monitor ADD command
                    operation.

                    A2L,H is the source field and A3L,H is maintained
                    as the pointer for the Monitor STORE command.

Dec  Hex   Monitor
Addr Addr  Label    Description

                    A2L,H contains the port number in an input port
                    select or output port select (control K or P)
                    command.

                    Monitor routine NXTAl increments AlL,H by one and
                    then compares the result to A2L,H. If A2L,H is
                    less than AlL,H then Carry is set when control is
                    returned to the calling program.

64   $40   A3L      Multipurpose Monitor work area:
65   $41   A3H      May be clobbered by Instruction Trace in the Old
                    Monitor; see XQT above.

                    AlL,H and A3L,H are both filled from A2L,H during
                    Monitor Command processing scan of the input line
                    as described above regarding AlL,H.

                    A3L,H is used as the destination pointer during
                    Monitor STORE command processing.

                    A3L,H is used as a work area by the Register
                    Display routine, which is called by the control-E
                    Monitor command, or as part of the single cycle or
                    trace operations of the Old Monitor.

66   $42   A4L      Multipurpose Monitor work area:
67   $43   A4H      May be clobbered by Instruction Trace in the Old
                    Monitor; see XQT above.

                    This field (and A5L,H) are loaded from A2L,H
                    during Monitor Command Processor scan of the input
                    area when a “<” character is encountered.

                    A4L,H is the receiving field pointer during a
                    Monitor MOVE command execution.

                    A4L,H is the second field pointer during a Monitor
                    VERIFY operation.

                    Monitor routine NXTA4 increments A4L,H by one, and
                    then drops into NXTAl, which increments AlL,H by
                    one and then compares the result to A2L,H. If
                    A2L,H is less than AlL,H then Carry is set when
                    control is returned to the calling program.

Dec  Hex   Monitor
Addr Addr  Label    Description

68   $44   A5L      Multipurpose Monitor work area:
69   $45   A5H      This field is not within the bounds of the area of
                    XQT, which, in the Old Monitor, overlays AlL
                    through A4H.

NOTE:
  A5H = $45 = ACC   This field is filled from A2L,H as described above
                    For A4L,H. However, the field is not otherwise
                    within the Monitor, except that ACC
                    (below) is also A5H.

69   $45   ACC      This five byte field is a register save area.
70   $46   XREG     With the following exceptions, the 6502 registers
71   $47   YREG     are stored by the SAVE routine and reloaded by the
72   $48   STATUS   RESTORE routine.
73   $49   SPNT

                      S-reg is stored at SPNT by SAVE but is never
                      reloaded.

                      The A-reg is stored at ACC by the IRQ routine on
                      either an IRQ interrupt or execution of a BRK
                      instruction. On a BRK, entry into the SAVE
                      routine at label SAV1 is used to store the rest
                      of the registers, The other registers are not
                      stored by the Monitor for an IRQ interrupt.

                    As described above, the registers are stored in
                    this area on execution of a RRK instruction.

                    After execution of a BRK instruction or on
                    execution of Monitor command control-E, the
                    contents of this area are used to display the
                    “registers” on the screen.

                    The registers (except S-reg) are loaded from this
                    area before jumping to the requested location on
                    execution of the Monitor G command.

                    In the Old Monitor Step and Trace command
                    routines, the registers are stored here after each
                    instruction execution and reloaded before the next
                    traced instruction is executed.

74   $4A   unused
75   $4B   unused
76   $4C   unused
77   $4D   unused

Dec  Hex   Monitor
Addr Addr  Label    Description

78   $4E   RNDL     Random number field, 16 bits:
79   $4F   RNDH     This field is continually counted up by the KEYIN
                    routine while testing for key pressed. Thus, the
                    results are effectively random as it doesn’t take
                    long to overflow and start over. There is no other
                    reference to this field within the Monitor.

80   $50   ACL      These three two-byte fields are used only by the
81   $51   ACH      multiply and divide routtnes in the Old Monitor.
82   $52   XTNDL    These routines are not called from any place in
83   $53   XTNDH    the Monitor. Therefore, these fields are used
84   $54   AUXL     only if a user program makes use of the multiply
85   $55   AUXH     or divide routines.

                    The section on Data Manipulation Functions
                    contains a full description of the multiply and
                    divide routines.

PAGES ONE THROUGH THREE
	
PAGE ONE ($0100-01FF)

Page one is the hardware stack area. Monitor use of this area is
only by means of the 6502 instructions which use the stack, such as
PHA, JSR, RTS, etc. The Monitor does not initialize or set the stack
pointer (S-register) on a RESET or Power On interrupt or at any other
time.

PAGE TWO ($0200-02FF)

Page two is the Keyboard Input buffer area. At label “GETLN” the
X-register is initialized as an index. At label ADDINP the character
read from the keyboard is stored into page two indexed by the
X-register. The result is that on return to the calling program the
characters read from the keyboard have been stored in memory locations
$0200 and up, the last character stored being a carriage return,
code $8D.

PAGE THREE ($0300-03FF)

Page three contains “vectors” for special handling of certain
interrupts at the high end of the page. The low end of the page,
through $03CF, is often used for machine language subroutines.
From $03D0 through $03EF is used by DOS.

PAGE THREE ADDRESS TABLE

Hex           Dec       Function

$0300-$03EF   768-1007  Not used by the Monitor.

$03F0-$03Fl  1008-1009  The Autostart Monitor uses this location as the
                        BRK instruction interrupt vector (address).

$03F2-$03F3  1010-1011  This is the RESET (Soft Entry) Vector (address)
                        used by the Autostart Monitor, as described in
                        the section “RESET Interrupt - Autostart
                        Monitor”.

$03F4        l012       Powered Up indicator: if the Exclusive OR of
                        “$A5” with the contents of $03F3 is equal to
                        the contents of $03F4 then the RESET (Soft
                        Entry) Vector is considered valid. Otherwise, a
                        RESET interrupt will cause the Autostart
                        Monitor to go through power-up initialization,
                        including boot of DOS if available.

$03F5-$03F7  1013-1015  Reserved for APPLESOFT (“&” vector instruction).

$03F8-$03FA  1016-1018  Control-Y Vector (instruction).

$03FB-$03FD  1019-1021  Non-Maskable Interrupt Vector (instruction).

$03FE-$03FF  1022-1023  IRQ Interrupt Vector (address).

PAGES FOUR THROUGH SEVEN & ELEVEN

Address range $0400 through $07FF is the primary text and low
resolution graphics display area. That is, screen display hardware
displays on the screen the information stored in this part of memory.

Address $0800 is generally the beginning of memory available to the
user for general program or data storage. However, $0800 through $0BFF
is the secondary text and low resolution graphics display area. By
POKEing -16299 with any value, the screen display hardware can be
directed to display to the screen from this secondary display area
instead of the primary display area. POKE -16300, 0 to switch back to
the primary display area.

Although the hardware will display to the screen from the secondary
display area, the Monitor does not support the feature. That is, the
BASCALC and GBASCALC routines in the Monitor convert the line number
input to the routine to the appropriate memory address for the primary
display area only. Use of the secondary display area is described in
the section “Secondary Display Areas”.

Contiguous screen lines are not in contiguous memory locations. The
characters on a screen line are in the same sequence in memory as on
the screen, but the lines are mixed in a manner which simplifies the
hardware display to the screen. The following table indicates for each
line the address in memory for the leftmost character of the line in
both the primary and secondary display areas.

The BASCALC routine in the Monitor computes the memory address for the
line number input to that routine in the A-reg. Using the letters to
designate bit positions in the input line number, the following
indicates the result of the computataion:

   Input line number (A-reg) 000ABCDE
   Memory address (BASH BASL) 000001CD EABAB000

This can be arithmetically computed, using “modulo” arithmetic in
place of the ANDs and ORs of machine language. For line number
“L” (0- 23),

   ADDR=l024+256*((L/2) MOD 4)+(128*(L MOD 2))+40*((L/8)MOD 4)

SCREEN MEMORY ADDRESS TABLE

       Line  Primary Display Area    Secondary Display Area
                Decimal    Hex          Decimal    Hex

        0        1024      0400          2048      0800
        1        1152      0480          2176      0880
        2        1280      0500          2304      0900
        3        1408      0580          2432      0980
        4        1536      0600          2560      0A00
        5        1664      0680          2688      0A80
        6        1792      0700          2816      0B00
        7        1920      0780          2944      0B80
        8        1064      0428          2088      0828
        9        1192      04A8          2216      08A8
       10        1320      0528          2344      0928
       11        1448      05A8          2472      09A8
       12        1576      0628          2600      0A28
       13        1704      06A8          2728      0AA8
       14        1832      0728          2856      0B28
       15        1960      07A8          2984      0BA8
       16        1104      0450          2128      0850
       17        1232      04D0          2256      08D0
       18        1360      0550          2384      0950
       19        1488      05D0          2512      09D0
       20        1616      0650          2640      0A50
       21        1744      06D0          2768      0AD0
       22        1872      0750          2896      0B50
       23        2000      07D0          3024      0BD0

It is also interesting to note that although 24 lines of 40 characters
computes to 960 bytes, the memory area described above contains 1024
bytes per display area. The significance is that some of the bytes in
pages four through seven are not displayed on the screen. These bytes
are eight groups of eight bytes each. This space has been set aside or
allocated for use by peripheral controller cards in slots one through
seven. The following table shows the allocation.

Misuse of these locations can be easily accomplished, with potentially
serious results. Note that if an image of the screen is generated
elsewhere and moved to this area in a block, the locations identified
below will be modified. If a program is loaded from tape with the
Monitor command mmmm.nnnnR, and if mmmm is less than $0400, then the
bytes in the following table will be loaded from the tape. If an
attempt is made to save the screen area to disk and later BLOAD it to
the screen area, results can be confusing. The Disk Controller card,
and possibly some peripheral device interface cards keep control
information in these areas. For example, doing the above mentioned
BLOAD from drive 2 when the BSAVE had been done from drive 1 will
result in the disk switching back to drive 1.

The Reference Manual indicates that one must be sure that Scroll
Window definition fields WNDLFT and WNDWDTH must not add up to more
than 40. Violation of the bytes in the following table will be the
unfortunate result if this caution is not observed.

PERIPHERAL CONTROLLER WORK AREAS
	
Common          Slot   Slot   Slot   Slot   Slot   Slot   Slot
(any/all)        1      2      3      4      5      6      7
Decimal  Hex

  1144   0478   0479   047A   047B   047C   047D   047E   047F
  1272   04F8   04F9   04FA   04FB   04FC   04FD   04FE   04FF
  1400   0578   0579   057A   057B   057C   057D   057E   057F
  1528   05F8   05F9   05FA   05FB   05FC   05FD   05FE   05FF
  1656   0678   0679   067A   067B   067C   067D   067E   067F
  1784   06F8   06F9   06FA   06FB   06FC   06FD   06FE   06FF
  1912   0778   0779   077A   077B   077C   077D   077E   077F
  2040*  07F8*  07F9   07FA   07FB   07FC   07FD   07FE   07FF

* Location 2040 ($07F8) has special significance. This location should
be loaded with $CN, where N is the slot number of the active
peripheral, whenever an interrupt may occur and the ROM/PROM expansion
scheme is in use. This is necessary so that the return from interrupt
software used allows the proper peripheral card to resume operation.

CHAPTER 2

INPUT AND OUTPUT

The default operation of the screen is as a scrolling device: new data
is entered or output at the bottom of the screen and all above is
shifted up line by line until the oldest information disappears off
the top of the screen. With a little extra work in the user program,
it is also possible to use the screen as a formatted display.
Following is a description of the effects of that type of use, and
some suggested solutions to the situations encountered.

Characters generated by the user program for display on the screen are
handed to the Monitor one character at a time. The screen output
handlers check for control character vs. display character, and operate
in accordance with what they find. For example, output of a carriage
return character or line feed character while the cursor is on the
bottom line of the screen will cause a scroll operation to take place.
If the screen is being used with a format instead of as a scroll
device, then the program can easily avoid output of a carriage return
or line feed when the cursor is on the bottom line of the screen.

The easiest way for the user program to read information from the
keyboard is to call the Monitor at the point where it will read in a
line (up to a carriage return) before returning control to the calling
program. When this is done, the input information is always available
at the same place in memory. There is, however, a conflict between
using this type of a call and using the screen as a format type
display. While the Monitor is receiving the keyboard input, it
“echoes” the characters to the screen at the current cursor location.
When end of input is signaled by a carriage return, the Monitor clears
the cursor current line from cursor to the right end of the line
(within the Scroll Window). Thus, the user program must make sure that
before asking for input from the keyboard the cursor is placed where
there is no significant data to the right.

It is possible to divide the screen into scroll area and non-scroll
area . Many complications arise from this method of operation, so the
recommended solution to the format display problem is to leave the
screen full scroll and avoid scroll services when they are not
desirable.

The entry points and qualifiers for using scroll and non-scroll areas
will be found in the section on Text Output Without the Scroll Window.

KEYBOARD INPUT DIVISION OF LABOR
	
The Monitor routines supporting keyboard input are designed to echo
the keyboard input to the screen (through COUT) at the current cursor
position, and store the entered characters in the keyboard input area
($0200-$02FF) for the convenience of the calling program. The
executing program may position the cursor anywhere (in the Scroll
Window) before calling the Monitor keyboard input routines. On entry
of a carriage return from the keyboard, the Monitor keyboard input
routines will cause return of control back to the calling program with
the character count plus one in the X-register and a carriage return
in the input area as a terminator. The program need not look into the
screen refresh memory to determine what was entered. (Note: The X-
Register begins with a zero, so that if five characters are entered,
the X-Register will reflect 4, although the actual value returned
will be 5. X is incremented for the carriage return as well.

The routines described below are included in the address table. The
following section, “User Program Calls ...”, describes program setups
for calling some of these entry points. Hex address, + Decimal
address, and - Decimal address are given in brackets beneath each
routine.

TABLE OF ROUTINES

Routine   Description

GETLNZ    Entry at this point causes output of a carriage return
[$FD67]   (through COUT) before going to GETLN to write the prompt
[64871]   character and read the data.
[- 665]

GETLN     Entry at this point is with the cursor properly positioned
[$FD6A]   (CV, BASL,H, and CH) as described in the section regarding
[64874]   Text Output Within the Scroll Window.
[- 662]
          GETLN prints the prompt character and initializes X-reg for
          indexed storage of the input characters into the input area.
          Control then goes to NXTCHAR.

NXTCHAR   This is the top point in the character input loop. RDCHAR
[$FD75]   is called to get a character into the A-reg. On return the
[64885]   A-reg is tested for presence of the control-U (right arrow on
[- 651]   the keyboard) and if it is found, the A-reg is then loaded
          from the screen refresh memory ((BASL),Y) assuming that the
          Y-reg contains the same value as CH.

          If the A-reg value is $E0 or greater, the lower case letter
          is converted to upper case by AND with $DF. The character is
          then stored from the A-reg to the input area.

          If the character is a carriage return, CLREOL is called to
          clear to blanks the rest of the window line, and then a
          conditional branch transfers control to COUT so that the RTS
          exit of COUT will return control to the calling program with
          the X-reg indicating the input character count +l, That is,
          the input is in memory locations $0200 through $0200, X where
          $0200, X contains the carriage return.

          If the character is not a carriage return, then control is
          transferred to the NOTCR routine for display on the output
          device, and for interpretation with regards to control
          character affecting the input line.

Routine   Description

NOTCR     This routine receives control with the character of interest
[$FD3D]   in (IN,X). The current setting of INVFLG is saved on the
[64829]   stack, while INVFLG is set to $ FF so that the character
[- 707]   “echoed” to the screen will be white on black. COUT is then
          called with the character in the A-reg.

          On return from COUT, INVFLG is restored from the stack. The
          character at IN,X is then tested for either of two special
          keys: Backspace (left arrow) or (line) Cancel (control-X).
          If Backspace, go to BCKSPC. If Cancel, go to CANCEL.

          If (IN,X) is neither Backspace nor Cancel the value of X-reg
          is tested to determine whether the input area is full or
          almost full. If there are more than 247 characters in the
          input area, a call to BELL is used to signal to the operator
          that the area is almost full.

NOTCRl    After or without the margin warning bell, this routine gets
[$FD5F]   control. Here, the X-reg is incremented to point at the
[64863]   next location in the input area to be filled. If, however,
[- 673]   the result is overflow to zero, then entry of the Cancel key
          is simulated by falling into CANCEL. In the normal case,
          after incrementing the X-reg, control goes back to NXTCHAR
          to continue with character input and line building.

CANCEL    This routine prints a back-slash through COUT to indicate
[$FD62]   the action taken to the operator. Control is then passed to
[64866]   GETLNZ to initialize for entry of a new input line - the old
[- 670]   one is gone.

BCKSPC    On entry to this routine, the backspace character has
[$FD71]   already been printed through COUT with resulting backward
(64881]   movement of the cursor. If the current value in X-reg is
[- 655]   zero, control is transferred back to GETLNZ for printing
          prompt and re-initializing for line input. Otherwise, the Xreg
          is decremented with control going to NXTCHAR to resume
          input of characters.

RDCHAR    This routine calls RDKEY to get the next character placed
[$FD35]   into the A-reg. If, on return, it is found that the Escape
[64821]   key has been pressed, this routine calls the appropriate
[- 715]   routine for reading the next character and performing the
          requested Escape key function. In the Old Monitor, control
          is passed to the ESCl routine for this purpose, after a JSR
          to RDKEY to read the next character. In the Autostart
          Monitor, detection at RDCHAR of an Escape character transfers
          control (via ESC including RDKEY) to ESCNEW, which has the
          capability of handling multiple escape functions after a
          single depression of the Escape key.

          After any requested escape functions have been performed,
          control returns to RDCHAR as if there had been no
          interruption.

Routine   Description

RDKEY     This routine picks up and saves in the A-reg the character
[$FD0C]   from the screen refresh memory area at BASL,H,CH (leaving
[64780]   the Y-reg filled with the contents of CH). It then changes
[- 756]   that character in memory to blinking to indicate current
          cursor position.

          This routine asks for the next input character to be placed
          in the A-reg by doing an indirect jump via KSWL,H, which is
          normally pointing at KEYIN. Return is therefore to the
          caller of RDKEY, not to the RDKEY routine itself.

KEYIN     This is the routine which gets the next input key from the
[$FD1B]   keyboard hardware. There are two required actions and two
[64795]   extra actions taken by this routine. The required actions
[- 741]   are reading the keyboard input buffer over and over again
          until it is determined (by presence of the $80 bit) that a
          character has indeed been read. In this case, keyboard input
          buffer refers to the $100 byte buffer at $200, and not to
          the location at $C000. The sign flag is set or not by
          checking the status of the value at $C000. If that value is
          positive, the routine loops back to KEYIN. If that value is
          negative, the value of $C000 is picked up and the keyboard
          strobe is referenced to prepare for the next keyboard input.

          The auxiliary actions taken by this routine are first, to
          count up the random number field, ignoring overflow, and
          second, to restore to the screen area the character modified
          by the RDKEY routine to remove the blink. This restore is
          accomplished by storing the A-reg at (BASL),Y, assuming that
          RDKEY loaded it. This is accomplished before the keyboard
          register is read into the A-reg.

          Return to the caller (of RDKEY) is accomplished by an RTS.

ESC       This routine is entered from RDCHAR if the A-reg is found to
[$FD2F]   contain the Escape key code. It reloads the A-reg with a new
[64815]   key by calling RDKEY. In the Old Monitor, it then calls ESCl
[- 721]   to perform the requested single function. In the Autostart
          Monitor, ESCNEW is called to perform the requested functions.
          In either case, ESC is positioned such that the RTS which
          terminates Escape key processing returns control to RDCHAR.

ESCNEW    This routine exists only in the Autostart Monitor. It is
[$FBA5]   the routine which supports cursor movement without data
[64421]   transfer; the Escape key functions I, J, K, and M. If the
[-1115]   key next pressed is one of these four, the appropriate “old”
          function (Escape functions C, B, A, and D, respectively) is
          called. On return to ESCNEW, RDKEY is again called to get
          (and operate upon) the next character from the keyboard.

Routine   Description

          If the key pressed is not I, J, K, or M, then ESCl is
          entered by JMP instead of JSR so that the RTS will return to
          the caller of ESCNEW instead of to ESCNEW.

ESCl      In the Old Monitor this routine is called by the RDCHAR
[$FC2C]   routine if the Escape key code is found in the A-reg by that
[64556]   routine. In the Autostart Monitor, control is passed in this
[- 980]   case to the ESCNEW routine which then calls ESCl or jumps to
          it depending on which key is pressed next.

          ESCNEW translates I, J, K, or M to C, B, A, or D
          respectively before calling ESCl, which returns to ESCNEW.

          If the key is other than I, J, K, or M, then ESCNEW JMP’s to
          ESCl with Carry set, to have the appropriate function
          performed. In this case, the next RTS will return control
          to the RDCHAR routine.

          When ESCl is called, the contents of the A-reg (and the
          condition that Carry is “set”) indicate the action to be
          taken, Control is transferred (conditional branch) to the
          appropriate Scroll Window Service routine to move the cursor
          without transferring data, or to clear all or some of the
          screen, or some combination of these.

CALLS TO KEYBOARD INPUT ROUTINES	

The following paragraphs describe how to set up for calls to the
various entry points in the Monitor for keyboard input, and what the
results will be.

TABLE OF KEYBOARD INPUT CALLS

Routine                  Description of Set-Up

GETLNZ   Write carriage return and prompt character, then read a line.

         Set-Up:
             X-reg, Y-reg, and A-reg are insignificant.
             CH is insignificant.
             CV should point to the line in the Scroll Window where
               input is to begin.
             BASL,H is insignificant.

         Results:
             CR is written, scroll takes place if appropriate.
             Prompt character is written through COUT.
             Keyboard is read character by character. Each character
             is placed at $0200,X and X is then incremented.

Routine                     Description

             Each character is “echoed” to the screen at cursor
               position and the cursor is then advanced.
             On reading a carriage return, control is returned to
               calling program.

         On Return:
             A-reg contains a carriage return code ($8D).
             X-reg contains the number of characters read before
               carriage return.
             Y-reg contains contents of WNDWDTH.
             Location $0200,X contains a carriage return.
             CH contains zero.
             CV contains line number, current value.
             BASL,H contains memory address for CV, WNDLFT.
             Window line is blank to the right of the end of the
               echoed input.

GETLN    Write prompt character, then read a line.

         Set-Up:
             X-reg, Y-reg, and A-reg are insignificant.
             CV and BASL,H should be compatible, pointing in the Scroll
               Window.
             CH indicates where on that line the prompt character is to
               be placed, to be followed by the echoed key input.
             Line address at which input is to begin must be in
               BASL,H. The Line number in CV will be calculated and
               set in BASL,H after a carriage return has been entered.

         Results:
             Same as above for GETLNZ, with noted exception.

         On Return:
             Same as above for GETLNZ.

NXTCHAR  Enter here to bypass print of prompt character to the screen.

         Set-Up:
             X-reg should be zero to begin st oring input at $0200.
             Y-reg and A-reg are insignificant.
             CV and BASL,H should be compatible, pointing in the Window.
             CH indicates where echoing of keyboard input is to start.

         Results:
             Same as above for GETLN.

         On Return:
             Same as above for GETLNZ.

Note: For all the above, Escape key functions are supported as
described in the reference material for the Monitor you have installed.
Also, control-U (right arrow) is supported. When that character is
recognized in the keyboard buffer, it is replaced in the A-register by
the contents of the screen memory at the current cursor position.

Routine                     Description

RDCHAR   Read single character thru KSWL: return to caller in A-reg.

         Set-Up:
             X-reg is insignificant, and will not be clobbered.
             Y-reg is insignificant.
             A-reg is insignificant.
             CV and BASL,H should be compatible, pointing in the
               Scroll Window to the line where input is to begin.
             CH indicates the horizontal position in the Scroll Window
               where cursor position will be indicated by blinking.

          Results:
             The screen character at the cursor position (BASL),(CH)
               will be set to blinking until a key is pressed.
             If the Escape key is detected, the appropriate routines
               will be called to handle the requested function.
             Cursor right arrow (control-U) will be returned to the
               calling program, not the contents of the screen at the
               cursor.
             Cursor left arrow key (control -H) will be returned to the
               calling program.
             Characters read from the keyboard will not be stored in
               the $0200 area.
             After the character is read, the blink will be turned off
               at the cursor position, but the key just read will not
               be echoed to the screen, nor will the cursor (CH) be
               advanced.
             Cancel input line (control-X) service is not defined
               as the data is not being stored in the $0200 area.
             No special note is taken of carriage return, because the
               rest of the Monitor KEYIN Routine is not called. It is
               up to the calling program to take appropriate action on
               entry of a carriage return.

         On Return:
             A-reg contains the value of the key pressed.
             Y-reg contains the contents of CH.
             X-reg is not affected by the routines called.
             CV, CH, BASL,H will have changed only if an Escape key
               function has been utilized.

RDKEY    Read single character thru KSWL: return to caller in A-reg.

         Set-Up:
             X-reg, Y-reg, and A-reg are insignificant.
             CV and BASL,H should be compatible, pointing in the
               Scroll Window.
             CH indicates the horizontal position where the cursor will
               be shown by blinking.

Routine                     Description

         Results:
             The character on the screen at the cursor position is set
               to blinking.
             KEYIN routine is given control via (KSWL) for physical
               reading of the keyboard.
             Return (RTS) in KEYIN returns to the caller of RDKEY, not
               to the RDKEY routine.

         On Return:
             A-reg contains the character from the keyboard. It may
               be any character, including Escape, carriage return,
               right or left arrow, or any other control character.
             X-reg is unchanged from the call.
             Y-reg contains the contents of CH.
             The character in the screen area at the cursor position
               has heen restored to whatever it was before it was set
               to blink by RDKEY.
             CV is used to calculate the new line.
             BASL,H reflects the recalculated address.
             CV remains unchanged.

KEYIN    Read single character from keyhoard: return to caller in A-reg.

         Set-Up:
             X-reg is unused and unaffected across this routine.
             A-reg input to this routine is what will be stored into
               the screen area at the cursor position (BASL),Y to
               remove the blink condition after a key is pressed.
             Y-reg is set to be used to store the A-reg into the screen
               area to remove the blink at (BASL),Y.
             CH and CV are not referenced, but should be appropriately
               set. BASL,H are used as described for A-reg and Y-reg
               above.

         Results:
             On return to the caller, only the A-reg has been changed.
             It contains the input from the keyboard register.

KEYIN ROUTINE REPLACEMENT

There are cases in which it is desirable to replace the physical
keyboard input routine with a routine which either reads from the
keyboard and preprocessee the input, or gets the information to feed
to the reading program from some source other than the keyboard. The
requirements of such a program in replacing the KEYIN routine are
described below. Placing the program/routine into effect is
accomplished by storing the entry point in KSWL,H.

The replacement routine should manage the following resources as
indicated.

    A-reg    Store the A-reg at (BASL),Y, then load the A-reg from
             whatever source is to be used.

    X-reg    Must be unaltered. Save on entry and restore on exit if
             it must be used by the replacement routine.

    Y-reg    Use as indicated above for A-reg.

             It must not be changed on return from contents on entry,
             so save and restore if it must be used otherwise. (This
             caution is not required, however, if the source of the
             input prevents Escape key and right arrow from being
             entered, In such case, the Y-reg is expendable.)

    CH       These are all used for echoing the “keyboard” input,
    CV       so the replacement routine should either leave them
    BASL,H   alone or manipulate them in an appropriate manner.

NOTE: On replacing the pointer to KEYIN at KSWL,H, it is generally
      safer to pick up and store the current contents of KSWL,H in a
      save area before placing the address of your routine, and then
      restore KSWL,H from that save area when taking the replacement
      routine out of service.

NOTE: If you replace the contents of KSWL,H with the address of your
      routine while using DOS, expect the unexpected, DOS uses both
      CSWL,H and KSWL,H, and periodically restores them to appear the
      way DOS likes to see them regardless of current contents.
      Depending upon your application, it may be a good idea to
      replace both pointers on a temporary basis so that echo to the
      screen will not pass through DOS, But remember to repair both as
      soon as possible.

KEYBOARD INPUT MONITOR ROUTINE
	
There are many points in Keyboard Service which a user program could
usefully call. However, because they are generally different locations
in a continuous string of instructions, and all instructions after the
point of entry will be used, sections of this table of addresses are in
Monitor sequence rather than in sequence by potential usability.

Note that once the Monitor is jumped to at the specified point, all of
the initialization described after that entry point is also performed.
This is implied by the & at the end of each function description.

ADDRESS TABLE 1—CHARACTER INPUT

Function                             Hex   +Dec  -Dec  Monitor  Registers
                                     Addr  Addr  Addr   Label   Destroyed
_________________________________________________________________________
BOTH MONITORS
Call RDKEY to get next character     FD35  64821 -715   RDCHAR   A,Y
  into A-reg.
Compare to $9B (Escape).
  If = BR to ESC to call for next
  character and do Escape function.
  Else, RTS.
Set screen to blink at cursor        FD0C  64780 -756   RDKEY    A,Y
  saving original character in the
  A-reg from (BASL),Y              &
Jump Indirect (KSWL) to KEYIN        FD18  64792 -744            A
Increment random number at RNDL,H    FDlB  64795 -741   KEYIN    A
  while polling keyboard register.
Store A-reg to (BASL),Y (clear       FD26  64806 -730
  blink set by RDKEY routine).     &
Load A-reg from keyboard register    FD28  64808 -728            A
  and clear keyboard strobe and RTS.

Using character in A-reg, with       FC2C  64556 -980   ESCl     A,Y
  Carry set, BR to routine for
  Escape key service.
    @ HOME     clear scroll window
    A ADVANCE  cursor right
    B BS       cursor left
    C LF       cursor down one line
    D UP       cursor up one line
    E CLREOL   clear to end of line
    F CLREOP   clr to end of window
    other      ignore: RTS

Set port 0 (keyboard) for input.     FE89  65161 -375   SETKBD   A,X,Y
----------------------------------------------------------------------
OLD MONITOR ONLY
Call RDKEY for Escape key service &  FD2F  64815 -721   ESC      A,Y
Call ESCl with character in A-reg    FD32  64818 -718            A,Y
  and Carry set to do indicated
  function. Return is to RDCHAR.
----------------------------------------------------------------------
AUTOSTART MONITOR ONLY
Call RDKEY for Escape key service &  FD2F  64815 -721   ESC      A,Y
Call ESCNEW with character in A-reg  FD32  64818 -718            A,Y
  and Carry set to do indicated
  function. Return from Escape
  processing is to RDCHAR (above).

Function                             Hex   +Dec  -Dec  Monitor  Registers
                                     Addr  Addr  Addr   Label   Destroyed
_________________________________________________________________________

Set Carry flag and JMP to ESCl       FB97  64407 -1129  ESCOLD    A,Y
  to handle Escape key functions
  A, B, C, D, E, F.

Handle Escape key functions          FB9B  64411 -1125  ESCNOW    A,Y
  I, J, K, M. Translate to
  D, B, A, C and call ESCOLD.
  Then RDKEY to get next character
  and drop into ESCNEW to continue
  Escape key processing.

Escape key processing entry point.   FBA5  64421 -1115  ESCNEW    A,Y
  If A-reg contains I, J, K, or M
  then go to ESCNOW to translate
  and handle it with return to
  ESCNEW. Otherwise go to ESCOLD
  to handle this entry and exit
  from Escape mode.
----------------------------------------------------------------------

BASL,H    40-41  $28-$29
KSWL,H    56-57  $38-$39

ADDRESS TABLE 2—LINE INPUT

Logically speaking, the place to start below is GETLNZ, but the
sequence of presentation here is the sequence of instructions in the
Monitor because of heavy use of “fall into” next code segment.

Note that once the Monitor is jumped to at the specified point, all of
the initialization described after that entry point is also performed.
This is implied by the & at the end of each function description.

Function                             Hex   +Dec  -Dec  Monitor  Registers
                                     Addr  Addr  Addr   Label   Destroyed
_________________________________________________________________________
Echo keyboard input thru COUT to     FD3D  64829 -707   NOTCR       A
  the screen, from IN,X, with
  INVFLG temporarily set to $FF.   &
Pick up character from IN, X;        FD4D  64845 -691               A
  if $88 goto BCKSPC.
  if $98 goto CANCEL.
  if X-reg (input index) greater
    than $F7 fall into FD5C.
  Else goto NOTCRl, bypass Bell.
Sound bell if X indicates 248+       FDSC  64860 -676
  input characters.                &
Increment X-reg;                     FDSF  64863 -673   NOTCRl      X
  If X not zero goto NXTCHAR.
  If X=0 fall into CANCEL.

Function                             Hex   +Dec  -Dec  Monitor  Registers
                                     Addr  Addr  Addr   Label   Destroyed
_________________________________________________________________________

Load $DC (\) into A-reg.             FD62  64844 -670   CANCEL    A,X,Y
  Backward slash indicates line
  input cancelled.                 &
Call COUT to print A-reg.            FD64  64868 -668
  Then fall into GETLNZ.           &
Print carriage return thru COUT.   & FD67  64871 -665   GETLNZ    A,X,Y
Load PROMPT into A-reg.            & FD6A  64874 -662   GETLN     A,X,Y
Call COUT to print A-reg.          & FD6C  64876 -660
Load X-reg with $01 for passage      FD6F  64879 -657             A,X
  thru backspace operation.
If X=0 goto GETLNZ to start over.    FD71  64881 -655   BCKSPC    A,X,Y
  Else, decrement X-reg and
  fall into NXTCHAR.
Call RDCHAR to get next character.   FD75  64885 -651   NXTCHAR   A
  If character received is ctrl-U
  ($95, right arrow) pick up the
  screen character from (BASL),Y
  to replace it in the A-reg.      &
If A-reg greater than $DF, then      FD7E  64894 -642   CAPTST    ?A
  AND against $DF to make it
  upper case.                      &
Store A-reg to input area at IN, X.  FD84  64900 -636   ADDINP
  Compare to carriage return.
   Goto NOTCR (above) if not.
   Else, call CLREOL to clear the
   rest of the line, then print
   carriage return thru COUT,
   using RTS from that function to
   accomplish return to caller of
   keyboard input.
----------------------------------------------------------------------
IN           =$0200, keyboard input area.
INVFLG       is at $32 (50).

OVERVIEW—TEXT OUTPUT TO THE SCREEN	

The highest level of support in the Monitor for text output to the
screen is scroll device support. In addition, the Monitor contains
many components which support use of the screen in a formatted manner.
Because there are so many ways to write text to the screen, the topic
of screen output has been divided into the following sections:

TEXT OUTPUT WITHIN THE SCROLL WINDOW
    describes the normal manner of text output, defining the fields in
    page zero which are used to control this function, and which are
    used in the descriptions in the following sections.

SCREEN FORMAT CONTROL
    identifies the entry points by means of which display operation
    (full text, full graphics, mixed LORES graphics and text), Scroll
    Window setup, and character display mode (black on white or white
    on black or blinking) are established or modified.

SCROLL WINDOW DATA MANIPULATIONS
    describes Monitor calls which clear all or part of the Scroll
    Window, set parts of the window to some user specified value, or
    cause conditional or unconditional scrolling of the window.

CURSOR POSITION CONTROL
    describes the ways and means of moving the cursor relative to its
    current position, or moving it to some location independent of its
    current position.

GENERAL TEXT TO THE SCREEN
    describes the Monitor entry points to output user program
    generated data to the screen or to the current output device if
    CSWL has been modified. Also, entry points are described to
    transmit standard types of output (blanks, bell code, carriage
    return) to the output device (generally screen).

TEXT OUTPUT WITHOUT THE SCROLL WINDOW
    describes the entry points used for placing characters on the
    screen out side of the Scroll Window, and for reading the keyboard
    when echo to the Scroll Window is to be performed.

SECONDARY DISPLAY AREAS
    describes various ways of using the Secondary Text area, even for
    limited Scroll Window functions such as allowing keyboard input
    echo to go to the Secondary area.

Any entry point which fits into more than one category will be found
in each appropriate address table.

OUTPUT WITHIN THE SCROLL WINDOW	

Scroll Window operation is compatible with printer or typewriter
output in that new characters are displayed to the right of previous
output, and new lines are displayed below previous lines. It is this
mode of operation which is described in this section. That is, this
section describes “printing” information by means of the CSWL vector
to the screen or to a printer type device. The section on General Text
to the Screen describes use of the screen, bypassing the CSWL vector
and making direct use of the Scroll Window output routines.

The normal method provided in the Apple II for displaying output
information is by “calling” COUT with the character in the A-reg for
each displayable character or format control character (such as a
carriage return). At COUT, a JuMP Indirect is done via the CSWL vector
to the routine which will place the character on the selected medium
or accomplish the indicated control function. When the system is
initialized, this vector is set to point to COUTl which supports
Scroll Window out put to the screen. If the user sets a different
output device (by PR#n in BASIC or ctrl-P in Monitor mode), then the
CSWL vector will be set to pass the output bytes to the selected
peripheral controller card instead of to the screen. Depending on
which peripheral controller card, and which controls are active, the
program on that card may place the character on the output device, and
then JuMP to COUTl to write it also to the Scroll Window.

The normal mode of text output to the screen is in “scroll” mode. In
this mode, new information is written to the bottom line of the
screen, and the contents of the screen are moved up, up, and away as
required to allow entry of new information below the old. This mode of
output is used in APPLESOFT or BASIC “PRINT” statements. This is the
mode of output used by any Monitor command which displays data to the
screen.

As new characters are written to the screen, they are placed at the
position of the cursor. The cursor position is a location on the
screen (and in screen refresh memory) specified by the contents of
certain fields in page zero. Also, the Scroll Window is a portion (or
all) of the screen as defined by the contents of certain fields in
page zero. There is no special display hardware involved with the
scrolling function. Routines in the Monitor move data in the screen
refresh memory as required to support the scrolling function.

The fields in page zero describing the Scroll Window indicate the left
column and width, and the top and bottom lines, as described here.

The cursor position is defined in various fields, and unless a user
program interferes they will be compatible.

The screen line number of cursor position is contained in the field
CV. CV indicates the line number of the cursor relative to the top
line of the screen, not the Scroll Window. (Note that this is
different from CH, described below.) The screen refresh memory
location which corresponds to this line number is maintained in the
two byte field (BASL,H). Note, however, that if the left edge of the
Scroll Window is not the leftmost character of the screen, BASL,H will
have been adjusted to point to the leftmost character position on that
line within the Scroll Window. Thus, a program may interrogate CV to
determine the line number of the cursor, but the program cannot just
POKE a different line number into CV to move the cursor as BASL,H must
be updated as well.

The horizontal position of the cursor is maintained in CH. The value in
CH is relative to the left edge of the Scroll Window, not necessarily
to the screen. When a character is being “written” or “printed” to the
screen, the routine which places the character in screen refresh memory
uses the Y-reg for horizontal position, in the assumption that it has
been loaded from CH. In the address table, each description indicates
whether the routine being called uses CH or the Y-reg.

For machine language programs, Scroll Window output is most easily
accomplished by a JSR to COUT at $FDED (-531) with the byte in the A-
reg. From BASIC the same thing is accomplished by PRINTing a variable
in which the byte has been stored. In BASIC, of course, a whole string
can be written with a single command.

As the characters are passed through COUTl, they are modified, if
necessary, to be written in white on black, black on white, or
flashing, in accordance with the contents of the field called INVFLG.
This field can be set (POKEd) at any time, and is immediately
effective on all future characters printed by the program until it is
again modified. This function only applies to program print output.
During keyboard entry, INVFLG is temporarily changed to $FF as each
input character is echoed through COUT.

The two byte field BAS2L,H is described below although it is rather
useless for user program reference. It is a work area used only
during a scroll operation.

PAGE ZERO FIELDS

Dec  Hex   Routine  Description

32   $20   WNDLFT   Left column of the Scroll Window:
                    Range is 0 to 39 ($27).
                    This field is used only in VTABZ. The contents,
                    when changed by user program, become effective on
                    the next scroll operation, clear to end of page
                    operation, or carriage return output. CH contains
                    cursor horizontal position relative to (WNDLFT).

                    After changing the contents of WNDLFT, either CALL
                    VTAB or output a carriage return to make it take
                    effect.

33   $21   WNDWDTH  Width of the Scroll Window:
                    Range is 1 to 40-(WNDLFT).
                    When a character is written through COUT to the
                    screen it is placed at (BASL),(CH), after which CH
                    is incremented. At that time (CH) is compared with
                    (WNDWDTH) to determine whether the cursor has
                    exceeded the right margin of the Scroll Window.

34   $22   WNDTOP   Top line of the Scroll Window:
                    Range is 0 to 22 ($16) for full text screen.
                    Range is 20 to 22 ($14 to $16) for mixed graphics
                    and text. This field is used during a scroll
                    operation to indicate where the operation should
                    start.

Dec  Hex    Routine  Description

35   $23    WNDBTM   Bottom line of Scroll Window +l:
                     Range is (WNDTOP)+l to 24 ($18).
                     WNDBTM indicates the first line number below the
                     window. Contents of WNDBTM are tested only on
                     output of a carriage return ($8D) or line feed
                     ($8A). It is used by Clear to End of Page and by
                     Scroll routines.

36   $24    CH       Displacement from WNDLFT where next character to
                     the screen will be placed:
                     Range is 0 to (WNDWDTH)-1.
                     After the screen output routine STOADV places a
                     character into the screen area as part of normal
                     character output, CH is then incremented and
                     compared to WNDWDTH. If CH is not low then a
                     carriage return will be simulated.

                     Note that CH is used for echoing keyboard input to
                     the screen by the Monitor routines GETLN etc.,
                     because COUT is used.

37   $25    CV       Vertical screen position (line number) for next
                     character to be written to the screen:
                     Range is 0 to 23 ($17).
                     The content of CV is relative to the top of the
                     screen, not to the top of the Scroll Window. It
                     may be set by loading the desired line number into
                     A-reg and calling TABV. It may be set by POKEing
                     the line number into CV and then calling VTAB.
                     Actual storage of a character into the screen area
                     includes use of BASL,H for line number, not CV.
                     The calls above to VTAB or TABV are to set BASL,H
                     from CV for immediate future reference.

                     If CV is at or below WNDBTM, it will remain on
                     current line as carriage returns go by while the
                     contents of the Scroll Window will be scrolled for
                     each.

40   $28    BASL     This two byte field is the memory address for the
41   $29    BASH     left end character position of the current text
                     line, within the Scroll Window. The contents are a
                     function of CV and WNDLFT.

                     This field is set by the BASCALC routine to point
                     to the memory address for the left end of the line
                     specified in the A-reg. This call to BASCALC is
                     usually accomplished by the VTAB routine, which
                     then adds (WNDLFT) to BASL,H to point to the left
                     end of the line within the window.

Dec  Hex   Routine  Description

42   $2A   BAS2L    This two byte field is used as a work area only
43   $2B   BAS2H    during a scroll operation. It is the destination
                    line pointer used as each line is moved to the
                    position above current.

50   $32   INVFLG   This byte is a mask used by COUTl to cause
                    characters written to the screen area to display
                    white on black (INVFLG=$FF) or black on white
                    (INVFLG=$3F) or flashing (INVFLG=$7F). This field
                    is set to $FF when a RESET occurs by the routine
                    at SETNORM. The routine called SETINV can be
                    called to set reverse video. The Monitor does not
                    set flashing.

                    Note: INVFLG=$7F does not cause all characters to
                    flash: the upper Z bits of the character must be
                    01 for flashing to occur.

53   $35   YSAV1    This byte is a save area for the Y-reg across a
                    call to the screen output routines. Y-reg is saved
                    and restored in the COUTl routine.

54   $36   CSWL     This two byte field contains the address of the
55   $37   CSWH     routine which is to receive and dispose of output
                    characters. When the RESET key is pressed, this
                    field is initialized to point to COUTl to send
                    output characters to the screen. Entering a
                    Monitor Command nPc (n=port number, Pc=control-P)
                    will cause the Monitor to set CSWL,H to Cn00. The
                    routine at that location will then receive (in the
                    A-reg) each byte “written” through COUT, which is
                    a JMP (CSWL).

                    If the Monitor Command “0Pc” is executed, CSWL,H
                    is set to point to COUTl instead of to C000.

SCROLL WINDOW OUTPUT ROUTINES

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Jump via CSWL, character print.      FDED  65005 -531   COUT    none
Write byte in A-reg to screen at     FDF0  65008 -528   COUTl   none
 cursor (CV), (CH) using INVFLG and
 supporting cursor move.
Write byte in A-reg to screen at     FDF6  65014 -522   COUTZ   none
 (CV), (CH) with cursor move but
 not INVFLG.

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Print carriage return thru COUT.     FD8E  64910 -626  CROUT     A
Print thru COUT “ERR” and bell code. FF2D  65325 -211  PRERR     A
Print bell code ($87) thru COUT.     FF3A  65338 -198  BELL      A
Set BASL,H from CV (and WNDLFT).     FC22  64546 -990  VTAB      A
Set BASL,H from (A) and WNDLFT       FC24  64548 -988  VTABZ     A
 without regard to CV.
Set BASL,H to left end of screen     FBCl  64449 -1087 BASCALC   A
 line (not window line) in A-reg.
----------------------------------------------------------------------
CH        36     $24         WNDLFT     32     $20
CV        37     $25         WNDWDTH    33     $21
GBASL,H   38-39  $26-27      WNDTOP     34     $22
BASL,H    40-41  $28-29      WNDBTM     35     $23
INVFLG    50     $32

SCREEN FORMAT CONTROL BY ROUTINE
	
This table identifies the places in the Monitor which control the
display mode of operation and the Scroll Window configuration.

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Clear HIRES graphics mode.        &  FB33  64307 -1229           A
Set display area primary.         &  FB36  64310 -1226           A
Set TEXT mode.                    &  FB39  64313 -1223 SETTXT    A
Load 0 into A-reg for WNDTOP,     &  FB3C  64316 -1220           A
 branch to SETWND below.

Set Graphics mode.                &  FB40  64320 -1216 SETGR     A,Y
Set mixed graphics/text mode.     &  FB43  64323 -1213           A,Y
Call CLRTOP to clear graphics.    &  FB46  64326 -1210           A,Y
Load 20 ($14) into A-reg for set  &  FB49  64329 -1207           A
 of WNDTOP. Fall into SETWND.

Set top line of window (WNDTOP)      FB4B  64331 -1205 SETWND    A
 from A-reg, 0 or 20 or user set.
 Fall thru following.
Load A-reg with 0 for WNDLFT.     &  FB4D  64333 -1203           A
Store A-reg to WNDLFT.            &  FB4F  64335 -1201           A
Load A-reg with 40 for WNDWDTH.   &  FB51  64337 -1199           A
Store A-reg to WNDWDTH.           &  FB53  64339 -1197           A
Load A-reg with 24 for WNDBTM.    &  FB55  64341 -1195           A
Store A-reg to WNDBTM.            &  FB57  64343 -1193           A
Load A-reg with 23 for VTAB.      &  FB59  64345 -1191           A
Store A-reg to CV.                &  FB5B  64347 -1189 TABV      A
Jump to VTAB - set BASL,H   RTS.

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Load Y-reg with $FF for INVFLG.      FE84  65156 -380 SETNORM   Y
 Fall into SETIFLG.
Load Y-reg with $3F for INVFLG.      FE80  65152 -384 SETINV    Y
 BR to SETIFLG.

Store Y-reg in INVFLG and RTS.       FE86  65158 -378 SETIFLG   none
  $FF white on black (from SETNORM)
  $3F black on white (from SETINV)
  $7F flashing (characters from user call with upper 2 bits of 01)

Set CSWL,H to point to COUTl.        FE93  65171 -365 SETVID    A,X,Y
----------------------------------------------------------------------
CH        36     $24         WNDLFT     32     $20
CV        37     $25         WNDWDTH    33     $21
INVFLG    50     $32         WNDTOP     34     $22
BASL,H    40-41  $28-29      WNDBTM     35     $23
CSWL,H    54-55  $36-37

SCREEN FORMAT CONTROL
BY POKE/STORE	

In many cases, the routine in the Monitor described on the previous
page exists because the Monitor itself uses the function described.
Often, calling the Monitor for a specific control function is doing it
the hard way. This table indicates other ways of accomplishing the
same results.

Function                            Method
_______________________________________________________________________
Set GRAPHICS display mode.          POKE -16304,0  or  STA C050
Set TEXT display mode.              POKE -16303,0  or  STA C051
Set GRAPHICS mode to full screen.   POKE -16302,0  or  STA C052
Set MIXED GRAPHICS and TEXT mode.   POKE -16301,0  or  STA C053
Set display to Primary Area.        POKE -16300,0  or  STA C054
Set display to Secondary Area.      POKE -16299,0  or  STA C055
Clear HIRES/Set LORES for graphics. POKE -16298,0  or  STA C056
Set HIRES Graphics mode.            POKE -16297,0  or  STA C057
Set top line of Scroll Window.      POKE 34,line-number (0-23)
                                    Bottom must be greater than top.
Set left edge of Scroll Window.     POKE 32,column-number (0-39)
                                    Left edge + width not to exceed 40.
Set width of Scroll Window.         POKE 33,number-of-columns (1-40),
                                    Left edge + width not to exceed 40.
Set bottom line of Scroll Window.   POKE 35,line-number (1-24)
                                    Bottom must be greater than top.
Set Normal (white on black) text.   POKE 50,255  or store $FF in $32
Set Flashing text.                  POKE 50,127  or store $7F in $32
Set Inverse (black on white) text.  POKE 50,63   or store $3F in $32

If the above means are used to change the Scroll Window configuration,
the user program should also take steps to insure that the cursor has
a valid position within the window (CV, CH, BASL,H). CALL -936 will
place the cursor in the Window.

$C050 and $C051 control Text mode vs. all or some graphics. The other
items regarding HIRES or LORES or full or part screen graphics may be
established first, but will not be apparent until $C050 is tickled.
Likewise, $C051 will bring back Text Mode regardless of the other
settings.

SCROLL WINDOW DATA MANIPULATIONS
	
This table describes three types of Scroll Window data manipulation
entry points. The first is Monitor label ESCl, the Escape Key
Processor, because it transfers control to a number of the other entry
points depending upon the A-reg contents and Carry being set. One
entry point of the Autostart Monitor is included because it handles
one requirement of ESCl - that Carry be set.

The second part of the table is a list of entry points supporting
clearing or setting parts of the screen to a particular value.

The third part of the table describes points causing conditional or
unconditional scrolling of the window.

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________

Call screen data manipulation.       FC2C  64556 -980   ESC1    A,Y
 If Carry is set and A-reg =
   @  goto   HOME
   A  goto   ADVANCE
   B  goto   BS
   C  goto   LF
   D  goto   UP
   E  goto   CLREOL
   F  goto   CLREOP
   other     RTS to caller.
 The RTS at the end of each of
  these functions returns control
  to the caller of ESCl.

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Clear from line (CV) col (CH) to     FC42  64578 -958 CLREOP    A,Y
 end of Scroll Window.
Clear from line (CV) col (Y) to      FC44  64580 -956           A,Y
 end of Scroll Window.
Clear from line (A) col (Y) to       FC46  64582 -954 CLEOPl    A,Y
 end of Scroll Window.
Clear Scroll Window to blanks,       FC58  64600 -936 HOME      A,Y
 set cursor to top left corner
 of the window.
Set CH=0, CV=(A), clear to EOP       FC5A  64602 -934           A,Y
 (end of page = end of window).
Clear window from line (A) to        FC5C  64604 -932           A,Y
 blank, set cursor to left end of
 line (CV).
Clear line from cursor               FC9C  64668 -868 CLREOL    A,Y
 ((BASL),(CH)).
Clear line from cursor (BASL),Y.     FC9E  64670 -866 CLEOLZ    A,Y
Set character in A-reg from          FCA0  64672 -864 CLEOL2    A,Y
 cursor (BASL),Y to EOLine.
Clear line (BASL), then set          FC95  64661 -875 SCRL3     A,Y
 BASL,H from CV and WNDLFT.
Clear line from cursor (BASL),Y,     FC97  64663 -873           A,Y
 then set BASL,H from CV & WNDLFT.
 CH remains unchanged.

Zero to A-reg for CH.            &   FC62  64610 -926 CR        A,?Y
Store A-reg to CH.               &   FC64  64612 -924           A,?Y
Increment CV.                    &   FC66  64614 -922 LF        A,?Y
Compare CV to WNDBTM.                FC68  64616 -920           A,?Y
 Set BASL,H; if (CV) < (WNDBTM),
 do scroll if required.

Scroll the window, lines (CV)        FC70  64624 -912 SCROLL    A,Y
 thru (WNDBTM).
Scroll the window, lines             FC72  64626 -910           A,Y
 (A) through (WNDBTM).

__________________________________		
Autostart Monitor extended service

Set Carry flag and JMP to ESCl       FB97  64407 -1129 ESCOLD   A,Y
 to handle Escape key functions
 A, B, C, D, E, F.

----------------------------------------------------------------------
CH        36     $24        WNDLFT      32     $20
CV        37     $25        WNDWDTH     33     $21
INVFLG    50     $32        WNDTOP      34     $22
BASL,H    40-41  $28-29     WNDBTM      35     $23

CURSOR POSITION CONTROL	

In general, the Cursor is at the position indicated by the contents of
CV (line number relative to top of screen) and CH (column number
relative to to the left margin of the Scroll Window). The memory
location of the cursor is the sum of the contents of BASL,H (which
contains the address of the leftmost character of the line within the
Scroll Window) and the contents of CH. Normally, then, BASL,H contains
an address computed from the contents of CV and WDLFT. However, if
either CV or WNDLFT is changed without recomputing BASL,H then the
different routines of the Monitor may come up with unpredictable (or
at least undesired) results.

In the following table, the description includes indication of which
of the cursor address fields is being used for what. Note, for
example, that at $FC95 the line indicated by BASL,H is cleared, and
then BASL,H is recomputed from CV, WDLFT for future references.

The ESCl and VIDOUT routines are included in the table because they
can be made to use (goto) the other entry points by passing them the
appropriate A-reg contents on entry. VIDOUT is the routine which
handles CR, backspace, and line feed when such characters are sent
through COUTl (generally thru COUT). ESCl is the routine called to
accomplish the desired function when the keyboard routines are
operating in ESCAPE key mode. Thus, it has four way cursor movement
capability, as well as the capability of clearing the Scroll Window
from cursor present position to end of current line or end of the
Scroll Window, or of clearing the entire Scroll Window and placing the
cursor at the top left corner of it. The function performed depends
upon the contents of the A-reg at entry, and the “set” condition of
the Carry processor status bit.

Entry point ESCOLD of the Autostart Monitor is included in the table
due to its relationship to ESCl.

The next group of points contains those which clear data on the screen
as well as move the cursor.

The third group is entry points supporting movement of the cursor
relative to its current position.

The fourth group supports positioning the cursor at a desired location
without reference to its current position. To do this, the program
should set CV and CH and then call VTAB to set BASL,H.

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Call screen/cursor manipulation.     FC2C  64556 -980  ESC1     A,Y
 If Carry is set and A-reg =
   @  goto   HOME
   A  goto   ADVANCE
   B  goto   BS
   C  goto   LF
   D  goto   UP
   E  goto   CLREOL
   F  goto   CLREOP
   other     RTS to caller.
 The RTS at the end of each of
 these functions returns control
 to the caller of ESCl.
Set Carry flag and JMP to ESCl       FB97  64407 -1129 ESCOLD   A,Y
 to handle Escape key functions                   Autostart only
 A, B, C, D, E, F.

Place character in screen memory     FBFD  64509 -1027 VIDOUT   A,Y
 or process control character .
 If (A) > $9F or < $80 goto STOADV.
 If (A) = $8D goto CR.
 If (A) = $8A goto LF.
 If (A) = $88 goto BS.
 If (A) = $87 sound “bell”.
 If (A) = other ignore it; RTS

Clear Scroll Window, set cursor to   FC58  64600 -936  HOME     A,Y
 top left corner of the window.
Set CH=0, CV=(A), clear to EOP       FC5A  64602 -934           A,Y
 (end of page = end of window).
Clear window from line (A) to        FC5C  64604 -932           A,Y
 blank, set cursor to left end of
 line (CV).
Clear line (BASL), then set          FC95  64661 -875  SCRL3    A,Y
 BASL,H from CV and WNDLFT.
Clear line from cursor (BASL),Y,     FC97  64663 -873           A,Y
 then set BASL,H from CV & WNDLFT.

Load Y from CH.                    & FBF0  64496 -1040 STOADV   A,Y
Store A-reg to screen at (BASL),Y  & FBF2  64498 -1038          A
Increment CH.                      & FBF4  64500 -1036 ADVANCE  A
Compare (CH) with (WNDWDTH)        & FBF6  64502 -1034          A
 goto CR if CH not less.
 Else return (RTS).
Move cursor left one column, to      FC10  64528 -1008 BS       A
 right end of previous line if
 required and (CV) < (WNDTOP).

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Move cursor up one line              FC1A  64538 -998   UP      A
 if (CV) < (WNDTOP).
Zero to A-reg for CH.              & FC62  64610 -926   CR      A,?Y
Store A-reg to CH.                 & FC64  64612 -924           A,?Y
Increment CV.                      & FC66  64614 -922   LF      A,?Y
Compare CV to WNDBTM.                FC68  64616 -920           A,?Y
 If CV not less decrement CV and
  do scroll.
 If CV less goto VTABZ to set
  BASL,H and return.

Place cursor at line (A) col (CH)    FB5B  64347 -1189  TABV    A
 (store A to CV and set BASL,H
 by JMP to VTAB).
Set BASL,H from CV and WNDLFT        FC22  64546 -990   VTAB    A
 by call BASCALC and add WNDLFT.
Set BASL,H from A-reg and WNDLFT     FC24  64548 -988   VTABZ   A
 by call BASCALC and add WNDLFT.
Set BASL,H to memory address for     FBC1  64449 -1087  BASCALC A 
 left character of line in A-reg
 (not left character of window).

Jump via CSWL, character print.      FDED  65005 -531   COUT    ?A
Character print to screen output     FDF0  65008 -528   COUT1   ?A
 routine entry - normal for CSWL.
 Print character to screen with
 appropriate actions on controls
 and control characters.
If (A)<$A0 goto COUTZ, bypass
 inverse video mask.
----------------------------------------------------------------------
AUTOSTART MONITOR ONLY
Print character to screen via        FDF6  65014 -522   COUTZ   none
 VIDWAIT (pause if operator request)
  and VIDOUT with save and restore
  of A reg and Y reg.
----------------------------------------------------------------------
OLD MONITOR ONLY
Print character to screen via        FDF6  65014 -522   COUTZ   none
 VIDOUT with save and restore
 of A reg and Y reg.
----------------------------------------------------------------------

CH        36     $24        WNDLFT      32     $20
CV        37     $25        WNDWDTH     33     $21
INVFLG    50     $32        WNDTOP      34     $22
BASL,H    40-41  $28-29     WNDBTM      35     $23

GENERAL TEXT TO THE SCREEN	

The preferred method of sending text to the screen is by loading the
character desired into the A-reg and calling COUT to handle it from
there. The reason this is preferred is that if you want to send the
output to some device other than the screen, you can change CSWL,H
to point at the program supporting such other device. There are
times, however, when you’ll want to write to the screen regardless of
the setting of CSWL,H. COUTl is the entry point for screen-only
output, where reverse video display or flashing characters are set
using INVFLG. Entry at this point for the Autostart Monitor also
allows you to stop output, using the control-S key.

COUTZ may be used for output to the screen without modifying the
character by using INVFLG. That is, calling COUTZ with a character in
the A-reg will place that character on the screen as is, without using
INVFLG to display the character in inverse video or flashing mode. In
the Autostart Monitor, entry at COUTZ is still early enough to handle
control-S entry, stopping the system if the character being written is
a Carriage Return while the keyboard buffer contains a control-S.

VIDOUT is the routine which interprets the character and places it on
the screen if it is not a control character. If the VIDOUT routine is
to be called directly (to bypass control-S handling in the Autostart
Monitor, for example), then the calling program must save the A-reg
and Y-reg before and restore the A-reg and Y-reg after, because they
are both destroyed in the VIDOUT routine.

Output to the screen may be written via these alternate entry points.
However, note that the Monitor will still use COUT for the keyboard
input echo function, temporarily setting INVFLG to $FF for white on
black for each character echoed.

Following are addresses of the above mentioned locations, and a few
other entry points which will output the specified character(s) (via
COUT) without the calling program having to load them into the A-reg
before the call.

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Print a byte to specified output     FDED  65005 -531  COUT     none
 device by JMP (CSWL), normally
 COUTl for screen.
Character print to screen output     FDF0  65008 -528  COUTl    none
 routine entry - normal for CSWL.
 Print character to screen with
 appropriate actions on controls
 and control characters.
 If (A)<$A0 goto COUTZ, bypass
 inverse video mask.
AND (A) with INVFLG.               & FDF4  65012 -524           ?A

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Print a byte to the screen.          FDF6  65014 -522  COUTZ     none
 See AUTOSTART and OLD differences
 toward end of this table.
Process char. in A-reg to screen.    FBFD  64509 -1027 VIDOUT    A,Y
 If control character, do control.
 If display character, store in
  screen refresh memory.
Store A-reg to screen at             FBF0  64496 -1040 STOADV    A,Y
 (BASL,H),(CH), then increment
 CH and goto CR if window exceeded.
Store A-reg to screen at (BASL,H),Y  FBF2  64498 -1038           A
 then inc CH and goto CR if window
 exceeded.
Increment CH and goto CR if window   FBF4  64500 -1036 ADVANCE   A
 exceeded.
Test CH. Goto CR if CH => WNDWDTH.   FBF6  64502 -1034           A
If A=$8D, $8A, $88, or $87 do it:    FC04  64516 -1020           A
 $8D carriage return goto CR
 $8A line feed       goto LF
 $88 back space      goto BS
 $87 bell            sound “bell”
Set INVFLG to $3F inverse video.     FE80  65152 -384  SETINV    Y
Set INVFLG to $FF normal video.      FE84  65156 -380  SETNORM   Y
Set INVFLG from Y-reg.               FE86  65158 -378  SETIFLG   none
----------------------------------------------------------------------
AUTOSTART MONITOR ONLY
Print character to screen via        FDF6  65014 -522  COUTZ     none
 VIDWAIT (stop if operator request)
  and VIDOUT with save and restore
  of A and Y regs.
Test for operator pause request.     FB78  64376 -1160 VIDWAIT   Y
 If (A)=$8D (carriage return), and
 if keyboard register is full, and
 if keyboard reg contains cntl-S,
 then fall into KBDWAIT.
 Else, goto VIDOUT.
Pause system per operator request.   FB88  64392 -1144 KRDWAIT   Y
 Loop until new key pressed.
  If next key pressed is cntl-C
   then goto VIDOUT, leaving cntl-C
   in keyboard register.
  Else, clear keyboard strobe and
   goto VIDOUT.
----------------------------------------------------------------------
OLD MONITOR ONLY
Print character to screen via        FDF6  65014 -522  COUTZ     none
 VIDOUT with save and restore of
 A-reg and Y-reg.
----------------------------------------------------------------------
CH        36     $24        WNDLFT      32     $20
CV        37     $25        WNDWDTH     33     $21
INVFLG    50     $32        WNDTOP      34     $22
BASL,H    40-41  $28-29     WNDBTM      35     $23

CONTROL CHARACTERS

Note:
The following control characters have special meanings for screen
display.

$8D Carriage Return
    In the Autostart Monitor, the COUTZ routine calls (JSR) VIDWAIT,
    which handles the control-S function before jumping to VIDOUT.
    The COUTZ routine in the Old Monitor calls VIDOUT.

    When the VIDWAIT routine determines that the character being
    “written” is a Carriage Return, it then tests the keyboard input
    buffer for a control-S. If so, it clears the keyboard hardware for
    another entry and loops until another key is pressed. If this
    entry is other than a control-C, the keyboard strobe is cleared.
    Otherwise the keyboard is left filled with the control-C for the
    calling program to detect and handle. Then VIDWAIT JMP’s to
    VIDOUT.

$8A Line Feed

    The cursor is moved down one line unless this would put it on a
    line below the Scroll Window. In that case, the contents of the
    Scroll Window are moved up one line, and the cursor stays on the
    current screen line.

$88 Backspace
    The VIDOUT routine moves the cursor to the left one space by
    decrementing CH. If CH goes negative it is set to (WNDWDTH)-1 and
    CV is decremented. If decrementing CV would take it above (WNDTOP)
    CV is not decremented. Negative scroll is not supported.

$87 Sound the Bell
    The speaker is pulsed 1000 times per second for one tenth of a
    second.

    Any other character in the range $80 thru $9F is dropped. It does
    not cause cursor motion or memory modification.

OUTPUT WITHOUT THE SCROLL WINDOW
		
If all or part of the screen is to be used in a direct addressing
manner, it is necessary to avoid certain Monitor services. In general,
the Scroll Window services provided by the Monitor are:

  1. Scroll all text in the window up one line if a carriage return
     or line feed takes the cursor down through the bottom line of
     the window.

  2. Automatically assume carriage return if window width is
     exceeded.

  3. Place the cursor at the left edge of the Scroll Window instead
     of at the left edge of the screen on a carriage return.

  4. Support screen clear functions:
     A. Clear the window, place cursor at top left corner.
     B. Clear the window from current cursor position.
     C. Clear line to the right of cursor position.

When using all or part of the screen as a random access display, these
automatic services need be avoided.

If the full screen is to be used as a random access display, without a
portion being used as a working Scroll Window, the problem is not too
difficult. Consider leaving the whole screen defined as the Scroll
Window.

  1. The scroll operation only occurs if a carriage return or line
     feed or exceeding window width occurs on the bottom line of the
     Scroll Window. Avoid this by not having the program output CR or
     LF or excessive data on the bottom line of the screen, and by
     keeping the cursor away from the bottom line of the screen
     during keyboard input operations.

  2. The full screen is defined as the Scroll Window by the Monitor
     when the RESET key is pressed. A user program can restore the
     window parameters to this configuration if they have been
     altered by calling “Set Normal Scroll Window” at $FB3C or 64316
     or -1220.

  3. Position the cursor where desired before printing a string of
     characters: POKE the line rrumber into CV and call VTAB for the
     line and then POKE the character number into CH.

  4. Output the string of characters by the same means as if operating
     with scroll services, being careful not to unintentionally
     exceed window width or output carriage returns. Depending on
     your screen design, however, you may intentionally do each of
     these.

Note that program output of a carriage return does not clear the line
to the right of the carriage return, but keyboard input of a carriage
return does (if reading the keyboard is being done by the Monitor get-
line routines).

If part of the screen is to be allocated as an operating Scroll Window
while the remainder of the screen is to be directly addressed, then a
different (lower) level of Monitor services must be called upon.

One way to support a divided screen is by using the Scroll Window for
data input with the Monitor get-input-line services, and by using the
Scroll Window support for whatever output the program intends to put
there. Then use parts of LORES graphics support for placing characters
on the screen outside of the Scroll Window, as described below. The
aim here is to leave support of cursor position (zero page fields CV,
CH, and BASL,H) up to the Monitor, and use other methods/fields for
placing characters outside the Scroll Window.

To place characters outside the Scroll Window,

  1. With the line rrumber in the A-reg, call GBASCALC to set GBASL,H
     to point to the memory address of the left character position of
     the indicated screen line.

  2. With Y-reg indicating horizontal position on the line, store the
     desired character at (GBASL),Y.

Note that this technique does not interfere with LORES plotting if the
screen is being used in mixed mode, because PLOT calls always set
GBASL,H as required without regard to possible previous contents.

Another approach is available for the BASIC or APPLESOFT programmer.
Again, the Scroll Window support can be used for some things, while
the following approach can be used to place characters on the screen
outside of the window. That approach is to compute the screen memory
location for each byte to the screen, and poke the byte there. A
variation on that approach is shown by the sample program. In the
sample, the Monitor VTAB routine is used to assist in building a table
of memory locations indicating the starting points of the screen
lines, This is an easier alternative than using the modulo arithmetic
formula described in the section “Pages Four thru Eleven”. Note that
adding 1024 to each value in the table gives the memory address for
that line in the secondary display area.

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
OUTSIDE OF SCROLL WINDOW
Compute memory address for line in   F847  63559 -1977 GBASCALC  A
 A-reg; set GBASL,H.

INSIDE SCROLL WINDOW
Write byte in A-reg to screen at     FDF0  65008 -528  COUT1     ?A
 cursor (CV),(CH) using INVFLG and
 supporting cursor move.
Write byte in A-reg to screen at     FDF6  65014 -522  COUTZ     none
 (CV),(CH) with cursor move but
 not INVFLG.
Clear Scroll Window to blanks,       FC58  64600 -936  HOME      A,Y
 cursor to top left corner.
Set CV from A-reg, clear window to   FCSA  64602 -934            A,Y
 end of window.

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Place cursor at line (A) col (CH)    FB5B  64347 -1189 TABV      A
 setting CV and BASL,H from A-reg.
Set BASL,H from CV (and WNDLFT).     FC22  64546 -990  VTAB      A
Set BASL,H from (A) and WNDLFT       FC24  64548 -988  VTABZ     A
 without regard to CV.
Set BASL,H to left end of screen     FBC1  64449 -1087 BASCALC   A
 line (not window line) in A-reg.
----------------------------------------------------------------------

CH        36     $24        WNDLFT      32     $20
CV        37     $25        WNDWDTH     33     $21
GBASL,H   38-39  $26-27     WNDTOP      34     $22
BASL,H    40-41  $28-29     WNDBTM      35     $23
INVFLG    50     $32

APPLESOFT SAMPLE PROGRAM

10     REM  TEXT OUTPUT WITHOUT THE SCROLL WINDOW
11     REM  SAMPLE PROGRAM
12     REM  READS FROM KEYBOARD LINE, CHAR, STRING
14     REM  AND PLACES THE STRING THERE
1000   REM  PROGRAM ENTRY
1010   DIM L%(23):     REM  LINE ADDR TABLE
1100   GOSUB 63000:    REM  MAKE UP TABLE
1199                   REM  PRINT PART OF TABLE JUST FOR SHOW
1200   FOR I = 0 TO 21: PRINT I,L%(I): NEXT
1209                   REM  DELAY TO ALLOW LOOK AT IT.
1210   FOR I = 1 TO 5000: NEXT
1220   PRINT:          REM  PRINT CR TO ALLOW CTL-S STOP IF DESIRED.
1225   CALL - 936:     REM  CLEAR SCREEN BEFORE CHANGING WINDOW.
1229                   REM  SET UP NEW WINDOW.
1230   POKE 32,24: POKE 33,14: POKE 34,12: POKE 35,17
1235   CALL -936:      REM  PUT CURSOR INTO WINDOW AREA.
1300   INPUT LI,CL,SS$:REM  READ A COMMAND LINE.
1399                   REM  ALLOW A WAY OUT
1400   IF SS$ = “END” THEN 63900
1500   SL = LEN (SS$)
1509                   REM  CHECK LEGALITY OF LINE, ETC.
1510   IF LI > 23 THEN 1810
1511   IF CL > 39 THEN 1810
1519                   REM  NOT PAST 40 THOUGH.
1520   IF CL + SL > 39 THEN SL = 40 - CL
1600                   REM  PUT CHARACTERS ONE AT A TIME.
1601   FOR I = 1 TO SL
1700   C$ = MID$ (SS$,I,l):C% = ASC (C$)
1720   POKE L%(LI) + CL + I - l,C% + 128
1740   NEXT I
1800   GOTO 1300:      REM  GO BACK FOR ANOTHER COMMAND.
1810                   REM  LINE OR CH TOO BIG - ERROR.
1811   CALL - 936: PRINT “NOT SO BIG”
1812   PRINT “LN “ ;LI: PRINT “CH “;CL
1820   GOTO 1800
62999                  REM
63000                  REM  MAKE UP LINE ADDRESS TABLE
63010  X% = PEEK (37): REM  REMEMBER CV
63020  FOR I = 0 TO 23
63030  POKE 37,I:      REM  SET CV
63031  CALL -990:      REM  CALL VTAB TO FILL BASL & BASH
63035  L%(I) = 256 * ( PEEK (41)) + PEEK (40)
63040  NEXT I
63045                  REM  TABLE SETUP DONE.
63046                  REM  RESTORE CV AND RETURN
63050  POKE 37,X%: CALL - 990: REM  WITH PROPER BASL & BASH
63060  RETURN
63900  CALL - 1233: END: REM  RESTORE FULL WINDOW PRIMARY

SECONDARY DISPLAY AREAS	
	
The Apple II hardware allows use of either of two memory areas for
display to the screen. The first, or primary, is memory locations
$0400-$07FF. The secondary text (and low resolution graphics) display
area is $0800-$0BFF. This area is normally overlaid by a user program
or data, but in special circumstances a user may desire to make use of
this secondary area as a screen display area.

The Monitor does not support the secondary display area as such. That
is, the routines in the Monitor which determine screen area memory
address from line number (CV) and character column (CH) do so only for
the primary display area. These routines perform correctly only for
lines 0-23.

Following are descriptions of two ways of using the secondary display
area.

COPY PRIMARY TO SECONDARY

There are times when it is desirable to change the display very
quickly, although the program produces the output slowly. For example,
a program might display data found by scanning a disk file. The
programmer might generate the original screen data in the primary
display area, then move it to the secondary display area and set the
hardware to display from secondary. The program may then proceed to
generate the next screen data in the primary area while the operator
is looking at the initial or previous display of results. A sample
program is provided later in this section showing how the Monitor Move
routine can be used to move the contents of the primary display area
to the secondary display area.

SET BASL,H FOR SECONDARY DISPLAY PAGE

When the Monitor places a character in the screen memory area, it does
so using BASL,H as the address of the memory location for the left end
of the line, and (CH) as the displacement from the left end of the
line. BASL,H can be initialized to the memory location of a selected
screen line by setting the desired line number in CV and then CALLing
TABV. On return from that CALL, adding 4 to BASH changes BASL,H to
point to memory for the desired line in the secondary display area.
This will last until the program writes a carriage return or writes
characters beyond the right end of the Scroll Window.

If the Monitor is called upon to read from the keyboard, it “echoes”
the input characters to the screen. Input of a carriage return, one
backspace too many, a cursor movement, or a screen clearing Escape
Key function will cause BASL,H to be restored by the Monitor to point
within the primary display area.

In the case where one display area is to be used for text and the
other for graphics, it is preferable to keep the graphics in the
primary area and the text in the secondary area because the Monitor
recomputes GBASL,H continually for plotting functions, whereas for
text output BASL,H is recomputed only when it is necessary to move the
cursor to a new line.

It must be noted that APPLESOFT also does not (easily) support the
secondary display area. APPLESOFT in RAM occupies that part of memory,
and then some. Firmware APPLESOFT places the program code in that
memory space, unless special actions are taken. Those actions may be
noted in the sample program, which uses APPLESOFT and the secondary
display area. POKE 104,12 and 3027,0 before loading the program.

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Place cursor at line (A), col (CH)   FB5B  64347 -1189 TABV     A
 (store A to CV and compute BASL,H
 by JMP to VTAB.
Set BASL,H from CV and WNDLFT        FC22  64546 -990  VTAB     A
 by call BASCALC and add WNDLFT.
Set BASL,H from A-reg and WNDLFT     FC24  64548 -988  VTABZ    A
 by call BASCALC and add WNDLFT.
Set BASL,H to memory address for     FBCl  64449 -1087 BASCALC  A
 left character of screen (not
 window) of line in A-reg.

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Write byte in A-reg to screen at     FDF0  65008 -528  COUTl    ?A
 cursor (CV),(CH) using INVFLG and
 supporting cursor move.
Write byte in A-reg to screen at     FDF6  65014 -522  COUTZ    none
 (CV),(CH) with cursor move but
 not INVFLG.
Monitor Command Processor MOVE       FE2C  65068 -468  MOVE     A (Y=0)
 routine. (AlL,H) thru (A2L,H) is
 moved to (A4L,H) thru whatever.
Monitor Command Processor GO entry.  FEB6  65206 -3301 GO       A,X,Y,P
 Set PCL,H from AlL,H if entered. &
 Call RESTORE, set all regs but S &  FEB9  65209 -327
 JMP via PCL,H.                      FEBC  65212 -324
----------------------------------------------------------------------

DIRECT CONTROL ADDRESSES

The following table describes the methods of setting the hardware for
display to various screen configurations by direct control rather than
by calling the Monitor. For some of these items there is no routine
in the Monitor which could be called to perform the function.

Function                              Method
_______________________________________________________________________
Set GRAPHICS display mode.          POKE -16304,0  or  STA C050
Set TEXT display mode.              POKE -16303,0  or  STA C051
Set GRAPHICS mode to Full Screen.   POKE -16302,0  or  STA C052
Set MIXED GRAPHICS and TEXT mode.   POKE -16301,0  or  STA C053
Set display to Primary Area.        POKE -16300,0  or  STA C054
Set display to Secondary Area.      POKE -16299,0  or  STA C055
Clear HIRES/Set LORES for graphics. POKE -16298,0  or  STA C056
Set HIRES Graphics mode.            POKE -16297,0  or  STA C057
Set top line of Scroll Window.      POKE 34,line-number (0-23)
                                    Bottom must be greater than top.
Set left edge of Scroll Window.     POKE 32,column-number (0-39)
                                    Left edge + width not to exceed 40.
Set width of Scroll Window.         POKE 33,number-of-columns (1-40),
                                    Left edge + width not to exceed 40.
Set bottom line of Scroll Window.   POKE 35,line-number (1-24)
                                    Bottom must be greater than top.
_______________________________________________________________________

CH        36     $24        WNDLFT      32     $20
CV        37     $25        WNDWDTH     33     $21
GBASL,H   38-39  $26-27     WNDTOP      34     $22
BASL,H    40-41  $28-29     WNDBTM      35     $23
INVFLG    50     $32

INTEGER BASIC SAMPLE PROGRAM

  10 REM  SAMPLE SECONDARY DISPLAY WAY
  11 REM  USING MONITOR MOVE TECHNIQUE
  19 GOTO 1000:              REM  BYPASS SUBROUTINES
  20               REM  MOVE AREA 1 TO AREA 2
  21 POKE 60,0: POKE 61,4:   REM SET A1L,H
  22 POKE 62,255: POKE 63,7: REM SET A2L,H
  23 POKE 66,0: POKE 67,8:   REM SET A4L,H
  25 POKE 71,0:              REM SET Y-REG=0
  26 POKE 58,44:             REM $2C
  27 POKE 59,254:            REM $FE
  28 CALL -327:              REM DO THE MOVE
  29 RETURN

1000             REM PROGRAM START
1001 IF PEEK (75)<12 THEN 32000

1100 CALL -936:              REM  CLEAR THE SCREEN

1200 PRINT “THIS IS THE SECONDARY DISPLAY AREA”
1210 PRINT “NOTE THE LACK OF CURSOR”

1300 GOSUB 20:               REM  MOVE TO SECONDARY

1400 CALL -936:              REM  CLEAR PRIMARY AGAIN
1410 PRINT “THIS IS THE PRIMARY AREA AGAIN”
1500 POKE -16299,0:          REM  SET SECONDARY
1600 FOR I=l TO 4000: NEXT I
1700 POKE -16300,0:          REM  BACK TO PRIMARY
1800 END

32000           REM  NO LOMEM ERROR
32001 PRINT “PLEASE LOAD AGAIN”
32002 PRINT “AFTER LOMEM:3072”
32003 END

APPLESOFT SAMPLE PROGRAM

10            REM SECONDARY DISPLAY AREA WAYS AND MEANS
11            REM SAMPLE PROGRAM
12            REM READS FROM KEYBOARD
13            REM COMMAND, LINE, CHARACTER, STRING
14            REM AND PLACES THE STRING

1000            REM PROGRAM ENTRY

1009            REM IS SECONDARY AREA CLEAR?
1010   IF  PEEK (104) < 12 THEN 62000

1020   GOSUB 63000:             REM CLEAR THE SECONDARY
                REM  M A I N   P R O G R A M
1300   IF Q = 0 THEN 1390:      REM INPUT TO PRIMARY
1309                            REM SET INPUT TO SECONDARY
1310   POKE 37,21:              REM SET LINE 21
1311   CALL - 990:              REM SET BASL,H
1312   POKE 41, PEEK (41) + 4:  REM SET BASH TO SECONDARY

1390   INPUT CC$,LI,CL,SS$
1400   IF CC$ = “END” THEN 63900
1410   IF CC$ = “S” THEN 2000:  REM SET SHOW TO SECONDARY AREA
1420   IF CC$ = “P” THEN 2100:  REM SET SHOW TO PRIMARY AREA
1430   IF CC$ = “Q” THEN 2200:  REM SET INPUT SECONDARY
1431   IF CC$ = “R” THEN 2300:  REM SET INPUT PRIMARY
1440   IF CC$ = “X” THEN 1500:  REM PUT STRING TO SECONDARY
1450   POKE 16300,0: PRINT “WHAT? “: GOTO 1300
1500   SL = LEN (SS$)
1510   IF LI > 23 THEN 1810
1511   IF CL > 39 THEN 1810
1512   IF CL + SL > 39 THEN SL = 40 - CL: REM NO AUTO CR
1590   CX = PEEK (37):          REM REMEMBER CV
1600   POKE 37,LI: CALL - 990: POKE 41, PEEK (41) + 4
1610   POKE 37,CX:              REM RESTORE CV
1620   POKE 36,CL:              REM SET CH FOR THIS PRINT
1700   SP$ = LEFT$ (SS$,SL):    REM SHORTEN PRINT IN THIS SMPL
1710   PRINT SP$
1800   GOTO 1300
1810   CALL - 936:              REM VALUE TOO LARGE.
1811   PRINT “NOT SO BIG”:      REM PRINT IN PRIMARY ONLY
1812   PRINT “LN “;LI: PRINT “CH “;CL
1820   GOTO l300

2000   POKE - 16299,0:          REM SET SECONDARY
2010   GOTO l300

2100   POKE - 16300,0:          REM SET PRIMARY
2110   GOTO l300

2200   Q = 1: GOTO 1300:        REM SET INPUT TO SECONDARY
2300   Q = 0: GOTO 1300:        REM SET INPUT TO PRIMARY

62000  PRINT “SETUP NOT MADE, NOW BEING DONE”
62010  PRINT “RUN THE PROGRAM AGAIN”
62018             REM 104 IS APPLESOFT ROM START
62019          REM BYTE BEFORE $C01 MUST BE ZERO
62020  POKE 3072,0: POKE 104,12: END

63000  BL$ = “     “:           REM CLEAR SECONDARY AREA
63001  FOR I = 1 TO 3: BL$ = BL$ + BL$: NEXT
63005  CX = PEEK (37)
63010  FOR I = 0 TO 23
63020  POKE 37,I: CALL - 990
63030  POKE 41, PEEK (41) + 4
63040  POKE 36,0
63050  PRINT BL$
63060  NEXT
63070  POKE 37,CX: POKE 36,0
63080  RETURN
63900  POKE 16300,0: CALL - 1233: END

CHAPTER 3

INTERRUPT PROCESSING

Some computers are capable of reacting to the raising (or dropping) of
a signal line by instantly saving the current status of the processor,
and quickly transferring control to some other program within the
computer. Changing the state of that line is called “causing an
interrupt”. The functions of the processor in saving its current state
and transferring control to some other location in memory is called
“taking an interrupt”. The program which then receives control is
expected to “handle the interrupt”.

The 6502 microprocessor in the Apple II is sensitive to three
interrupt categories. These are RESET, NMI (Non-Maskable Interrupt),
and IRQ. Execution of a BRK instruction causes a form of IRQ interrupt
to be simulated.

The purpose of an interrupt, in general, is to allow some kind of
external device to make a condition known to a running program without
the program having to periodically or continually test for the
hardware condition. An example of the latter type of operation is the
Apple II keyboard operation. When keyboard input is to be accepted
memory location $C000 is tested repeatedly until presence of the sign
bit indicates that a key has been pressed. An example of interrupt
driven processing could be a special peripheral controller card,
attached to a telephone line, which caused the computer to be taken
over by a data acquisition program any time data was available, but
would allow the machine to be used for other things in between
transmissions.

When a computer recognizes (takes) an interrupt, the hardware should
accomplish three things.

   1.  Save processor status in such a way that execution of the
       interrupted program can be continued after the interrupt has
       been “serviced” or handled.

   2.  Prevent further recognition of that class of interrupts until
       the interrupt handling program restores that interruptability.

   3.  Transfer control to the program meant to handle this type or
       category of interrupt.

With the 6502 in the Apple II variations on the above three steps are
taken for the three different interrupt classes or categories.

   1.  When an IRQ (or BRK) or NMI interrupt is taken, the contents of
       the program counter and the P-reg (processor status register)
       are respectively pushed onto the stack. When a RESET interrupt
       is taken, the processor holds the memory in READ mode until
       control is transferred to the handler, so nothing of processor
       status is pushed onto the stack.

   2.  When the 6502 takes an IRQ interrupt, the P-reg is modified. If
       a BRK instruction is executed, the $10 bit of the processor
       status register is set to one before the P-reg is pushed onto
       the stack. If the IRQ line was the cause of the interrupt, this
       bit is set to zero before the P-reg is pushed onto the stack.

       After the P-reg is pushed onto the stack, the $04 bit is set to
       inhibit recognition of any more IRQ category interrupts until
       the interrupt handling program clears this condition.

       With RESET and NMI there is no available facility for
       preventing another interrupt while the current interrupt is
       being handled.

   3.  The 6502 transfers control to the appropriate program for
       handling an interrupt by means of “vectors”. Memory addresses
       $FFFA-$FFFF are reserved for this purpose. The final step of
       taking an interrupt is loading of the program counter from the
       vector for this class or category of interrupt. The following
       table indicates the locations of the interrupt handlers for the
       two Monitors.

          Interrupt  Vector    Monitor  Old Monitor  Autostart
           Taken     Address    Label     Address     Address
          					
          NMI        $FFFA-B    “NMI”      $03FB       $03FB
          RESET      $FFFC-D    RESET      $FF59       $FA62
          IRQ/BRK    $FFFE-F    IRQ        $FA86       $FA40

NMI INTERRUPT

       The Apple II Monitor does not interfere with user handling of
       the NMI interrupt. That is, the vector for NMI causes the 6502
       to transfer control of the computer to location $03FB, where
       the user is to place a JMP to the user-provided handler for
       this type of interrupt.

RESET INTERRUPT SUPPORT

       Pressing the RESET key on the keyboard causes a RESET interrupt
       to occur. On all Apple II’s but the very early ones, power-on
       also results in generation of a RESET interrupt.

       The actions performed by the Autostart Monitor and the Old
       Monitor RESET interrupt handlers are considerably different.
       Therefore, they will be described separately.

IRQ/BRK INTERRUPT HANDLING

       When either an IRQ interrupt is taken or a BRK instruction is
       executed, the 6502 performs an interrupt sequence. The contents
       of the program counter are pushed onto the stack. The $10 bit
       of the P-reg is set or cleared to indicate the IRQ line vs.
       BRK instruction, and then it is pushed onto the stack. The 6502
       then sets the $04 bit of the P-reg, preventing another
       interrupt of this type from being recognized until this one is
       handled. The 6502 then loads the Program Counter from the IRQ
       hardware prescribed vector at $FFFE-$FFFF, and allows operation
       of the computer to continue from that point. The Interrupt
       Handler for IRQ interrupts is now in control.

RESET INTERRUPT—OLD MONITOR
		
When a RESET interrupt is taken the Old Monitor establishes a
predefined configuration of hardware and page zero fields. Primarily,
the keyboard is set as the current input device, the screen is set as
the current output device, and the screen configuration is set to full
screen Scroll Window with normal video.

Page zero fields KSWL,H, CSWL,H are set to make the keyboard and
screen active. WNDLFT, WNDWDTH, WNDTOP, WNDBTM are set to define the
whole screen as the Scroll Window. CV and CH are set to place the
cursor at the bottom left corner of the screen. INVFLG is set to
normal (white on black).

Hardware addresses are referenced to establish a known configuration
as follows.

$C056 - clear high resolution graphics
$C054 - display primary area
$C051 - set text mode

Control is then transferred to the “top” of the Monitor at label MON,
location $FF65, at which point the “bell” is sounded and the Monitor
enters the command line read routine.

ADDRESS TABLE
Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Set STATUS in SAVE area to 0.      & FB2F  64303 -1233 INIT      A
Clear HIRES.                       & FB33  64307 -1229           A
Set primary display area.          & FB36  64310 -1226           A
Set TEXT mode.                     & FB39  64313 -1223 SETTXT    A
Set full screen scroll window by     FB3C  64316 -1220           A
 branch to SETWND with (A)=0.
Set WNDTOP from A-reg.             & FB4B  64331 -1205 SETWND    A
Load A with 0 for WNDLFT.          & FB4D  64333 -1203           A
Set WNDLFT from A-reg.             & FB4F  64335 -1201           A
Load A with 40 for WNDWDTH.        & FB51  64337 -1199           A
Set WNDWDTH from A-reg.            & FB53  64339 -1197           A
Load A with 24 for WNDBTM.         & FB55  64341 -1195           A
Set WNDBTM from A-reg.             & FB57  64343 -1193           A
Load A with 23 for CV.             & FB59  64345 -1191           A
Set CV from A-reg.                 & FB5B  64347 -1189 TABV      A
JMP to VTAB to set BASL,H & RTS.     FB5D  64349 -1187           A
Set INVFLG to $FF = normal video.    FE84  65156 -380  SETNORM   Y
Set INVFLG from Y-reg.               FE86  65158 -378  SETIFLG   none
Set port 0 (keyboard) for input.     FE89  65161 -375  SETKBD    A,X,Y
Set port 0 (screen) for output.      FE93  65171 -365  SETVID    A,X,Y
----------------------------------------------------------------------
Monitor entry on RESET key pressed   FF59  65369 -167  RESET
 or Power on.
 Call SETNORM - white on black.    &
 CalL INIT - Text & full scroll.   & FF5C  65372 -164
 Call SETVID - screen as output.   & FF5F  65375 -161
 Call SETKBD - keyboard = input.   & FF62  65378 -158
Clear 6502 decimal mode (set hex)  & FF65  65381 -155  MON
Sound bell.                        & FF66  65382 -154
Monitor Command Processor Entry.     FF69  65385 -151  MONZ
 Set “*” as prompt character.

RESET INTERRUPT—AUTOSTART MONITOR
		
The Autostart Monitor performs functions of three categories in
handling a RESET interrupt.

   1.  Establish a known hardware/software environment with regards to
       the basic machine.

   2.  If the contents of memory (page three) do not indicate that a
       power-on initialization has been performed, the Autostart
       Monitor will perform power-on initialization. If a disk
       controller card is present in one of the slots, power-on
       initialization includes bootstrapping from that slot. If no
       disk controller card is in the machine a control-B entry is
       simulated. In either case, the appropriate language processor
       receives control at the end of power-on initialization, with
       page three fields set to indicate that a warm start is to be
       performed on ensuing interrupts from the RESET key.

   3.  If the contents of memory (page three) indicate that power-on
       initialization has already been performed, the Autostart
       Monitor will transfer control via the RESET (Soft Entry) vector
       in page three at the conclusion of “handling” the RESET
       interrupt. If DOS has been booted, this will result in transfer
       of control back to the current language processor through DOS.
       If DOS is not present, the normal setting of the RESET vector
       will cause simulation of a control-C (warm start) reentry into
       the current language.

INITIALIZE SYSTEM CONFIGURATION

When a RESET interrupt is taken, the Autostart Monitor establishes a
predefined configuration of hardware and page zero fields. Primarily,
the keyboard is set as the current input device, the screen is set as
the current output device, and the screen configuration is set to full
screen Scroll Window with normal video.

Page zero fields KSWL,H, CSWL,H are set to make the keyboard and
screen active. WNDLFT, WNDWDTH, WNDTOP, WNDBTM are set to define the
whole screen as the Scroll Window. CV and CH are set to place the
cursor at the bottom left corner of the screen. INVFLG is set to
normal (white on black).

Hardware addresses are referenced to establish a known configuration
as follow.

$C056 - clear high resolution graphics
$C054 - display primary area
$C051 - set text mode
$C058 - clear AN0 = TTL LO
$C05A - clear ANl = TTL LO
$C05D - set AN2 = TTL HI
$C05F - set AN3 = TTL HI
$CFFF - turn off Expansion ROH
$C010 - clear keyboard strobe

On completion of all the above, the Autostart Monitor sounds the BELL.

COLD/WARM DETERMINATION

After establishing a known basic hardware and software (screen
controls) environment, the Autostart Monitor executes a test to
determine whether power-on initialization is to be performed. Page
three locations $03F2-$03F3 contain the RESET (Soft Entry) vector, the
address to which the Autostart Monitor will transfer control on
completion of handling the RESET interrupt. Location $03F4 is a
validation byte, used with $03F3 to indicate whether or not power-on
initialization is to be performed. If the Exclusive OR of the contents
of these two memory locations is $A5, then power-on initialization is
considered to have been previously accomplished, and $03F2-$03F3 is
considered a valid address to which to transfer control.

POWER-ON INITIALIZATION

The first functions of power-on initialization are to establish in
page three ($03F0-$03F4) the BRK interrupt vector (see “BRK
Instruction Handling - Autostart Monitor”) and the RESET Soft Entry
interrupt vector with validation byte. The RESET vector at this point
is set to $E000 to simulate a control-B (initialize) entry for the
current language processor.

The Autostart Monitor next performs a routine which tests each slot,
from slot 7 through slot 1, for presence of a disk controller card.
If one is found, a jump is performed to $CX00 where X is the slot
number in which the disk controller has been found. This will result
in loading of DOS and presumably execution of the HELLO program.
Note: DOS 3.2 Replaces the RESET vector at $03F2-$03F3 and validation
byte at $03F4, so that on a RESET interrupt, control will be passed
through DOS back to the current language processor.

If no disk controller card is found the Autostart Monitor changes the
RESET vector to $E003 (language restart or control-C entry point) and
then jumps to $E000 (language initialize entry point).

SYSTEM RESTART

If the $03F3-$03F4 test described above is passed, the RESET vector at
$03F2-$03F3 is considered mostly valid. If it contains $E000, it is
changed to $E003 and then BASIC is entered at $E000. If it is not
$E000, it executes an Indirect Jump via $03F2-$03F3 to the address
specified therein.

RESET VECTOR MODIFICATION BY USER

The RESET vector may be modified by user or program to send control to
some other address in the machine at the completion of Monitor
handling of the interrupt; For example, to cause the RESET key to
result in placing the machine in Monitor mode, execute the following
program;

10 POKE 1010,105
20 POKE 10ll,255
30 POKE 1012,90
40 CALL -151: REM ENTER MONITOR
50 END

The following program is more general purpose. In order to set the
RESET vector to some address, poke the address into locations 1010-
1011 ($03F2-$03F3) and then CALL Autostart Monitor label SETPWRC
($FB6F or 64367 or -1169) to set location 1012 ($03F4).

10 REM AD IS ADDRESS OF
11 REM ROUTINE TO RECEIVE
12 REM CONTROL AFTER RESET
20 POKE 1010,AD: REM SET LO BYTE
30 POKE 1011,AD/256: REM SET HI
40 CALL -1169: REM SET 1012

Note: If you try to run this on a system with an Old Monitor ROM, you
may destroy the program, or even the entire diskette. To avoid this
problem, execute the steps in the above program manually, on a system
with an Autostart ROM. Then, PEEK location 1012 and get the value to
POKE into 1012, alleviating the need to CALL-1169 at all.

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Monitor entry on RESET key pressed   FA62  64098 -1438 RESET
 or Power on.
  CLD - clear 6502 dec,(set hex).  &
  Call SETNORM - white on black.   & FA63  64099 -1437
  Call INIT - Text, full scroll.   & FA66  64102 -1434
  Call SETVID - screen as output.  & FA69  64105 -1431
  Call SETKBD - keyboard as input  & FA6C  64108 -1428
Initialize hardware to known state.  FA6F  64111 -1425 INITAN
 Clear AN0 to TTL LO (ref. C058).  &
 Clear ANl to TTL LO (ref. C05A).  & FA72  64114 -1422
 Set AN2 to TTL HI (ref. C05D).    & FA75  64117 -1419
 Set AN3 to TTL HI (ref. C05F).    & FA78  64120 -1416
 Clear Expansion ROM (ref. CFFF).  & FA7B  64123 -1413
 Clear keyboard strobe.            & FA7E  64126 -1410
Clear 6502 decimal mode (set hex). & FA8l  64129 -1407 NEWMON
Call BELL.                         & FA82  64130 -1406
Test $3F3 vs. $3F4: Cold or Warm     FA85  64133 -1403
 If Cold goto PWRUP.
 If ($3F3) XOR ($3F4) = $A5, Warm.
Test SOFTEV ($3F2) low byte:         FA8F  64143 -1393
 Non-zero means Cold Start done -
  Goto NOFIX to use SOFTEV vector.
 Zero means restart warm maybe.
Test SOFTEV hi for $E0 - language    FA94  64148 -1388
 cold start entry. If not equal,
 SOFTEV is ok to use, goto NOFIX.
SOFTEV = $E000, change to $E003 for  FA9B  64155 -1381 FIXSEV
 future use and goto $E000 to cold
 start the language.

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
JMP (SOFTEV): Use the Soft Entry     FAA3  64163 -1373 NOFIX
 vector to exit RESET handler.
Cold Start on RESET entry point.     FAA6  64166 -1370 PWRUP
 Call APPLEII to clear screen and
  put title on top line.           &
Set page 3 interrupt vectors for     FAA9  64169 -1367 SETPG3
 BRK (OLDBRK) and SOFTEV ($E000).
Look for disk controller card in     FAB4  64180 -1356
 slots 7 thru 1. If none, goto
 FIXSEV above to set SOFTEV for
 BASIC restart & enter BASIC cold.
 If disk found, JMP (LOC0) to boot
 from the disk.
Clear screen (call HOME).          & FB60  64352 -1184 APPLEII   A,Y
Place APPLE II legend on top line.   FB63  64355 -1181           A,Y
Set PWREDUP ($3F4) = ($3F3) XOR $A5  FB6F  64367 -1169 SETPWRC   A
Set STATUS in SAVE area to 0.      & FB2F  64303 -1233 INIT      A
Clear HIRES.                       & FB33  64307 -1229           A
Set primary display area.          & FB36  64310 -1226           A
Set TEXT mode.                     & FB39  64313 -1223 SETTXT    A
Set full screen scroll window by     FB3C  64316 -1220           A
 branch to SETWND with (A)=0.
Set WNDTOP from A-reg.             & FB4B  64331 -1205 SETWND    A
Load A with 0 for WNDLFT.          & FB4D  64333 -1203           A
Set WNDLFT from A-reg.             & FB4F  64335 -1201           A
Load A with 40 for WNDWDTH.        & FB51  64337 -1199           A
Set WNDWDTH from A-reg.            & FB53  64339 -1197           A
Load A with 24 for WNDBTM.         & FB55  64341 -1195           A
Set WNDBTH from A-reg.             & FB57  64343 -1193           A
Load A with 23 for CV.             & FB59  64345 -1191           A
Set CV from A-reg.                 & FB5B  64347 -1189 TABV      A
Jump to VTAB to set BASL,H & RTS.    FB5D  64349 -1187           A
Set INVFLG to $FF = normal video.    FE84  65156 -380  SETNORM   Y
Set INVFLG from Y-reg.               FE86  65158 -378  SETIFLG   none
Set port 0 (keyboard) for input.     FE89  65161 -375  SETKBD    A,X,Y
Set port 0 (screen) for output.      FE93  65171 -365  SETVID    A,X,Y

FOR COMPATIBILITY WITH OLD MONITOR   FF59  65369 -167  OLDRST
 the RESET routine is still here.
 Call SETNORM - white on black.    &
 Call INIT -Text & full scroll.    & FF5C  65372 -164
 Call SETVID - screen as output.   & FF5F  65375 -161
 Call SETKBD - keyboard = input.   & FF62  65378 -158
Clear 6502 decimal mode, set hex.  & FF65  65381 -155  MON
Sound bell.                        & FF66  65382 -154
Monitor Command Processor Entry.     FF69  65385 -151  MONZ
 Set “*” as prompt character.

IRQ/BRK INTERRUPTS	
	
IRQ/BRK INTERRUPT RECOGNITION

When either an IRQ interrupt is taken or a BRK instruction is executed
the 6502 performs an interrupt sequence. The contents of the program
counter are pushed onto the stack. The $10 bit of the P-reg is set or
cleared in indication of IRQ line vs. BRK instruction, and then it is
pushed onto the stack. The 6502 then sets the $04 bit of P-reg,
preventing another interrupt of this type from being recognized until
this one is handled. The 6502 then loads the Program Counter from the
IRQ hardware prescribed vector at $FFFE-$FFFF, and allows operation of
the computer to continue from that point. The Interrupt Handler for
IRQ interrupts is now in control.

IRQ INTERRUPT HANDLING

The 6502 directing vector at $FFFE-$FFFF points to Monitor program
label IRQ in both the Old Monitor and the Autostart Monitor. It will
be noted in the address table that the address is different, however.

The handling of an IRQ interrupt is identical in both Monitors. The
contents of the A-reg are stored at ACC ($45) for future reference.
The processor status (P-reg) pushed onto the stack by the taking of
the interrupt is popped into the A-reg, and then pushed back onto the
stack so that the stack and pointer are not changed. By shifting the
A-reg left three bits, the IRQ routine moves into the sign bit the bit
which indicates (in this case by being a zero) that the interrupt is
an IRQ interrupt rather than execution of a BRK instruction. The
Monitor then executes a Jump Indirect instruction via location $03FE-
$03FF to the user provided IRQ Interrupt Handler. Note that on an IRQ
interrupt the X, Y, and S registers are not saved by the Monitor.
Also, the interrupt handler has the responsibility of clearing the $04
bit on exit to allow further interrupts.

BRK INSTRUCTION INTERRUPT

Execution of a BRK instruction causes the 6502 to simulate an IRQ
interrupt with minor changes. Due to the method the instruction is
handled, the address pushed onto the stack as part of the interrupt
simulation is two bytes beyond the BRK instruction executed.

Before pusbing the P-reg onto the stack, the $10 bit is set to
indicate to the internipt handling routine that the cause of the
interrupt was execution of a BRK instruction rather than the IRQ line.
After pushing the P-reg onto the stack, the $04 bit is set to inhibit
IRQ interrupts from being recognized until the interrupt handler
clears the condition. Control is then transferred according to the
6502 IRQ interrupt vector to Monitor label IRQ. As described above
regarding handling of an IRQ interrupt, the IRQ routine first stores
the A-reg at ACC ($45) for future reference, and then uses the A-reg
to test the stacked P-reg contents for a one in the $10 position. The
stack and stack pointer are not changed by this operation. The result
of the test is a transfer of control to Monitor label BREAK. Note in
the address table that the address of BREAK is not the same in the two
Monitors.

BRK INSTRUCTION—SAVING OF STATUS

In each Monitor the first thing done in the BREAK routine is to save
full machine status in page zero. The contents of the A-reg have
already been stored by entry into the IRQ interrupt handler. The BREAK
routine pops the stacked contents of the P-reg from the stack, and
does a JSR to SAVl at which point the remaining registers are saved.
Note that this clears the $04 bit, allowing further IRQ or BRK
interrupts to be taken. The S-reg saved at that time, however, has
been incremented once by popping the P-reg back from the stack and
decremented twice by the JSR to SAVl. On return from SAVl, the BREAK
routine pops the Program Counter from the stack and stores it in page
zero locations PCL-PCH. The address table at the end of this section
indicates the page zero locations at which the above items are stored.

BRK INSTRUCTION—OLD MONITOR

The function of the BRK instruction interrupt handler of the Old
Monitor is to display through COUT the machine status at the time the
BRK instruction was encountered, and then return control to the top of
the Monitor at label MON. The details above describe the handling of
the interrupt through storage of machine status in page zero,
including PCL,H. The Old Monitor BREAK routine next does a JSR to
INSDSl to display the instruction at the address indicated by PCL-PCH
(which is two bytes beyond the BRK executed), and a JSR to RGDSPl to
display the contents of the five registers, P, A, X, Y, S. Note that
the S-reg as displayed is two less than it was at the time of the BRK
execution due to the JSR to SAVl. On completion of the register
display, a JMP to MON completes the handling of the interrupt.

BRK INSTRUCTION—AUTOSTART MONITOR

The Autostart Monitor handles IRQ interrupt which is really a BRK
instruction interrupt by saving registers and Program Counter in page
zero locations. The Autostart Monitor BREAK routine then exits via the
Apple-II BREAK vector at $03F0-$03Fl. Thus, it is possible for a user
program to gain control at that point and do something other than to
display the registers and return to the Monitor command processor.
Such a program must be sure to clear the $04 bit in the P-reg on
return. During RESET interrupt handling for power-on, this vector is
initialized to point at Autostart Monitor label OLDBRK, which routine
does the same thing as was done in Old Monitor. That is, it does a JSR
to INSDSl to display the disassembled instruction at the location
indicated by PCL-PCH, a JSR to RGDSPl to display the register
contents, and a JMP to MON to complete the handling of the interrupt.
Note: after DOS 3.2 has destroyed page 3 during the bootstrap
operation, it restores this vector to point to $FA59, OLDBRK.

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Disassemble the instruction at       F8D0  63696 -1840 INSTDSP  A,X,Y
 (PCL, H), print thru COUT.
Display registers thru COUT from     FAD7  64215 -1321 REGDSP   A,X
 save area, after carriage return.
Display registers thru COUT from     FADA  64218 -1318 RGDSPl   A,X
 save area.
Save 6502 regs at $45-49.            FF4A  65354 -182  SAVE     A,X
 Save A-reg at ACC $45.            &
 Save X-reg at XREG $46.           & FF4C  65356 -180  SAV1
 Save Y-reg at YREG $47.           & FF4E  65358 -178
 Save P-reg at STATUS $48.         & FF50  65360 -176
 Save S-reg at SPNT $49.           & FF54  65364 -172
 Clear 6502 decimal mode (set hex).
Clear 6502 decimal mode (set hex)  & FF65  65381 -155  MON
Sound bell.                        & FF66  65382 -154
Monitor Command Processor Entry.     FF69  65385 -151  MONZ
 Set “*” as prompt character.

AUTOSTART IRQ/BRK HANDLING

Determine whether interrupt was      FA40  64064 -1472 IRQ      A
 IRQ or BRK, transfer control
 accordingly.
Handle BRK interrupt:                FA4C  64076 -1460 BREAK    A,X,Y
 Restore P-reg from stack.
 Save registers (SAVl) X,Y,P,S.
 Move interrupt location from stack
  to PCL,H.
 JMP (BRKV) to possibly user
  specified routine (normally to
  OLDBRK, below).
Default BRK interrupt handler        FA59  64089 -1447 OLDBRK   A,X,Y
 completion routine
 Display instruction (2 bytes past),
 Display registers, JMP to MON.

OLD MONITOR IRQ/BRK HANDLING

Determine whether interrupt was      FA86  64134 -1402 IRQ      A
 IRQ or BRK, transfer control
 accordingly.
Handle BRK interrupt:                FA92  64146 -1390 BREAK    A,X,Y
 Save registers,
 Display instruction (2 bytes past),
 Display registers, JMP to MON.
----------------------------------------------------------------------
PCL,H   58,59   $3A,3B                   YREG    71    $47
ACC     69      $45                      YSAV    52    $34
XREG    70      $46                      STATUS  72    $48

CHAPTER 4

MISCELLANY

MACHINE LANGUAGE DEVELOPMENT AIDS

There are many routines in the Monitor which can be helpful when
developing machine language programs. Some of these are routines to be
used in the finished program, like the Monitor MOVE routine. Others
in this list are general, special, or very special screen output
routines, and some data manipulation routines.

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
-----------------------------------------------------------------------
Write byte in A to screen at CV, CH. FDED  65005 -531  COUT      ?A
Print carriage return thru COUT.     FD8E  64910 -626  CROUT     A

Print three blanks thru COUT.        F948  63816 -1720 PRBLNK    A,X
Print (X) blanks thru COUT.          F94A  63818 -1718 PRBL2     A,X
Print character in A followed by     F94C  63820 -1716 PRBL3     A,X
 (X)-1 blanks.
Print BELL code thru COUT.           FF3A  65338 -198  BELL      A
Print “ERR” and BELL thru COUT.      FF2D  65325 -211  PRERR     A

Print low nibble of A as hex char.   FDE3  64995 -541  PRHEX     A
Print A-reg as 2 hex nibbles.        FDDA  64986 -550  PRBYTE    A
Print hex of Y,X regs.               F940  63808 -1728 PRNTYX    A
Print hex of A,X regs.               F941  63809 -1727 PRNTAX    A
Print hex of X-reg.                  F944  63812 -1724 PRNTX     A
Print CR, then hex of Y,X regs,      FD96  64918 -618  PRYX2     A,Y
 then minus sign (or dash).
Print hex of Y,X regs, then dash.    FD99  64921 -615            A,Y
Print CR, hex of AlH,AlL, and dash.  FD92  64914 -622  PRA1      A,X,Y
Print memory as hex with preceeding  FDA3  64931 -605  XAM8      A (Y=0)
 address from mmmm to mmm7 where
 mmmm is initial content of AlL,H.
Print memory as hex from (AlL,H)     FDB3  64947 -589  XAM       A (Y=0)
 thru (A2L,H).

Save A,X,Y,P,S regs at $45-49.       FF4A  65354 -182  SAVE      A,X
Display registers with names from    FAD7  64215 -1321 REGDSP    A,X
 $45-49 as SAVEd, with preceeding
 carriage return.
Display regs as above without CR.    FADA  64218 -1318 RGDSP1    A,X
Restore regs A,X,Y,P not S from $45  FF3F  65343 -193  RESTORE   A,X,Y,P

Monitor Command Processor GO entry.  FEB6  65206 -330  GO        A,X,Y,P
 Set PCL,H from AlL,H if entered.  &
 Call RESTORE, set all regs but S. & FEB9  65209 -327
 Jump via PCL,H.                     FEBC  65212 -324
Move memory contents to (A4L,H)      FE2C  65068 -468  MOVE      A (Y=0)
 from (AlL,H) thru (A2L,H).

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
-----------------------------------------------------------------------
Compare memory contents (A4L,H)      FE36  65078 -458  VFY      A (Y=0)
 to (AlL,H) thru (A2L,H), print
 differences thru COUT.
Increment A4L,H ($42-43).          & FCB4  64692 -844  NXTA4    A
Increment AlL,H ($3C-3D), set Carry  FCBA  64698 -838  NXTA1    A
 if A2L,H less than AlL,H.
Set GBASL,H for line (A).            F847  63559 -1977 GBASCALC A
Clear A-reg to a nibble, leaving     F879  63609 -1927 SCRN2    A
 in low nibble entry low nibble if
 entry carry clear, high nibble if
 entry carry set.
Disassemble the instruction at       F8D0  63696 -1840 INSTDSP  A,X,Y
 (PCL,H), print thru COUT.
Compute (PCL,H) + (LENGTH), leave    F953  63827 -1709 PCADJ    A,X,Y
 results in A,Y. Decimal Mode Flag
 must be clear before calling PCADJ.
Read paddle (X) into (Y-reg).        FB1E  64286 -1250 PREAD    A,Y
Wait .01 seconds, then sound bell.   FBDD  64477 -1059          A,Y
Load Y=l92 for .1 sec of bell.     & FBE2  64482 -1054          A,Y
Toggle speaker at 1 KHZ for number   FBE4  64484 -1052 BELL2    A,Y
 of cycles in Y-reg.
Place character in screen refresh    FBFD  64509 -1027 VIDOUT   A,Y
 memory if not control character.
 If known control character, do it.
 If unknown control character, RTS.
Clear window to blank, set cursor    FC58  64600 -936  HOME     A,Y
 to top left corner.
Load 0 into Y, then print dash.      FD9C  64924 -612
Print dash thru COUT.                FD9E  64926 -610
Character print to screen output     FDF0  65008 -528  COUT1    ?A
 routine entry - normal for CSWL.
 Print character to screen with
 appropriate actions on controls
 and control characters.
 If (A)<$A0 goto COUTZ, bypass
 inverse video mask.
Monitor entry on RESET key pressed   FF59  65369 -167  RESET
 or Power on.
 Call SETNORM - white on black.    &
Clear 6502 decimal mode (set hex). & FF65  65381 -155  MON
Sound bell                         & FF66  65382 -154
Monitor Command Processor Entry.     FF69  65385 -151  MONZ
 Set “*” as prompt character       &
 Set (a) as prompt character       & FF6B  65387 -149
Monitor Command Processor command    FFA7  65447 -89   GETNUM
 parsing routine; save hex digits
  in A2L,H, return with command
  (first non-hex) in A-reg, Y-reg
  set for next character.
----------------------------------------------------------------------
AlL,H  60,61  $3C,3D    A4L,H  66,67  $42,43    YREG   71    $47
A2L,H  62,63  $3E,3F    PCL,H  58,59  $3A,3B    XREG   70    $46
A3L,H  64,65  $40,41    ACC     69      $45

LORES PLOTTING	
	
In standard (or low resolution) plotting mode, the graphic area of the
screen is 40 points wide and either 40 points high with 4 lines of
text below or 48 lines high. The X coordinate is horizontal and the Y
coordinate is vertical. The same memory area is used for low
resolution plotting as is used for text output to the screen. However,
in the graphics mode, each character position contains information for
two plot points, one immediately above the other. Thus, 20 text lines
are used to display 40 graphics lines in the mixed mode, and 24 text
lines are used to display 48 graphics lines in the full screen mode.

There are four bits allocated for each point; by means of which the
point may be displayed in any of 16 colors.

The Monitor contains routines supporting the following functions:

    Set display mode to mixed graphics and text.

    Clear the graphics part of the screen (in whole or in limited
    part).

    Set a color control byt e to be used for each plot point
    established until another color is selected.

    Plot a single point at an indicated vertical/horizontal position.

    Plot a horizontal line from one vertical/horizontal point to a
    vertical value.

    Plot a vertical line from one vertical/horizontal point to a
    vertical value.

    Return to requesting program the color value of the point at a
    specified coordinate.

There are limitations on some of these functions which may not always
be desirable. For example, using the entry point which sets mixed
graphics and text includes clearing the graphics part of the screen,
setting the Scroll Window to be the entire remainder of the screen,
and moving the cursor (straight down from current position) to the
bottom line of the screen. In addition, there is no Monitor entry
point for setting full screen graphics mode. However, the display mode
controls are easily set in any desired fashion merely by poking or
storing into the appropriate memory locations, so this is certainly no
major problem.

Various page zero locations are used for low resolution graphics mode.

PAGE ZERO FIELDS

         Dec    Hex
Routine  Addr.  Addr.    Description

GBASL,H  38-39  $26-27   is set by the GBASCALC routine to the memory
                         address of the plotting line specified.

COLOR    48     $30      contains the selected color value in both high
                         and low nibbles of the byte.

MASK     46     $2E      is used internally by the plot routines as $F0
                         or $0F to set either the high or low nibble of
                         the receiving byte depending on whether the
                         graphics line is the top or bottom of the two
                         displayed from that “text” line.

H2       44     $2C      is the right end point for horizontal line
                         drawing.

V2       45     $2D      is the bottom end point for vertical line
                         drawing.

ADDRESS TABLE

Function                            Hex   +Dec  -Dec Monitor Registers
                                    Addr  Addr  Addr  Label  Destroyed
----------------------------------------------------------------------
Plot a point at line (A) col. (Y)   F800 63488 -2048  PLOT     A
 leaving GBASL,H and MASK set.
Plot a point, line per GBASL,H      F80E 63502 -2034  PLOT1    A
 and MASK, col. in Y.

Draw horizontal line at (A) from    F819 63513 -2023  HLINE    A,Y
 (Y) thru (H2), left to right.
Draw horizontal line at line        F81C 63516 -2020  HLINEl   A,Y
 indicated by GBASL,H. MASK from
 (Y) thru (HZ).
Plot vertical line at (Y) from      F828 63528 -2008  VLINE    A
 (A) thru (V2).

Plot vertical line at (Y) from      F826 63526 -2010  VLINEZ   A
 (A)+l+carry thru (V2).
Plot vertical line at (Y) from      F82D 63533 -2003           A
 (A)+l thru (V2).
Clear full (48 lines) screen.       F832 63538 -1998  CLRSCR   A,Y
Clear graphics area (40 lines).     F836 63542 -1994  CLRTOP   A,Y
Clear graphics partial from line 0  F838 63544 -1992  CLRSC2   A,Y
 thru (Y), 40 col. wide.
Clear graphics partial from line 0  F83A 63546 -1990           A,Y
 to (V2) 40 col. wide.
Clear graphics partial, top left    F83C 63548 -1998  CLRSC3   A,Y
 lines 0 thru (V2),col. 0 thru (Y).

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Set LORES screen to COLOR from top   F840  63552 -1984           A,Y
 left corner to (Y), (V2).
 Entry A-reg must be 0.
 Entry Y-reg = right column to set.
 Set V2 to last line to set.
Set COLOR for following points       F864  63588 -1948  SETCOL   A
 to (A).
Change COLOR to (COLOR)+3.           F85F  63583 -1953  NXTCOL   A
Load to A color of point (A),(Y).    F871  63601 -1935  SCRN     A
Set GBASL,H from A. (A)=line/2.      F847  63559 -1977  GBASCALC A
Set Color Graphics display mode      FB40  64320 -1216  SETGR    A,Y
 and following are also done;
Set graphics mode to mixed.        & FB43  64323 -1213           A,Y
Clear graphics part of screen.     & FB46  64326 -1210           A,Y
Load $14 to A for WNDTOP.          & FB49  64329 -1207           A
Store A to WNDTOP.                 & FB4B  64331 -1205  SETWND   A

Load 0 to A for WNDLFT.            & FB4D  64333 -1203           A
Store A to WNDLFT.                 & FB4F  64335 -1201           A
Load $28 to A for WNDWDTH.         & FB51  64337 -1199           A
Store A to WNDWDTH.                & FB53  64339 -1197           A
Load $18 to A for WNDBTM.          & FB55  64341 -1195           A
Store A to WNDBTM.                 & FB57  64343 -1193           A
Load $17 to A for CV.              & FB59  64345 -1191           A
 Go to TABV to set BASL,H.
----------------------------------------------------------------------
						
DATA MANIPULATION FUNCTIONS

There are a number of routines in the Monitor which may be called by
user programs to perform often needed tasks. The routines described in
this section are miscellaneous routines which move data from place to
place or convert the form of information provided to the routines.
Note that some of these routines are in both the Old Monitor and the
Autostart Monitor while other routines are in only one or the other.
Three address tables are provided; one for both Monitors, one for the
Old Monitor, and one for the Autostart Monitor.

ROUTINES

Memory to Memory Move

This routine is used by the Monitor “M” command. As the Command
Interpreter scans the keyboard input, fields Al, A2, and A4 are
loaded. When the Command Interpreter encounters the “M” it calls label
MOVE, as indicated in the table. The contents of memory from locations
(Al) thru (A2) are moved to memory beginning at location (A4). See the
sample program in the section “Secondary Display Area Ways and Means”
for use of MOVE from BASIC, with the assistance of the Monitor GO
routine for setting registers on the way in.

Jump to Address with Registers Loaded

The routine in the Monitor which responds to the “G” command uses some
Monitor routines from BASIC or APPLESOFT in that the registers are
loaded from the save area and then control is transferred to the
location specified in PCL,H. Thus, a BASIC program can set up the
destination address and register contents, and then CALL -468 to have
the requested routine entered. This is used in sample programs in this
section and in the section on “Secondary Display Areas”.

Increment Address Fields

The Monitor Move routine described above is a sample caller of the
NXTA4 and NXTAl routines. When NXTA4 is called, it increments the two
byte field A4L,H and then falls into label NXTAl. The routine at NXTAl
increments the two byte field at AlL,H, and then compares that field
to the two byte field A2L,H before returning to the calling program.
On return to the calling program, the Carry status bit is clear if
(AlL,H) is less than or equal to (A2L,H). Carry is set if (AlL,H) is
greater than (A2L,H).

Save 6502 Registers

The SAVE routine is used by various other Monitor routines to store
the 6502 registers in page zero locations $45-$49. This routine may
be called by user program under certain conditions - namely, that
neither the Monitor nor any other program will be calling SAVE at the
same time. In the Old Monitor SAVE and RESTORE are used in support of
Monitor commands S and T, single step and instruction trace, In both
Monitors, the SAVE routine is called on a BRK interrupt at entry point
SAV1 as the A-reg is stored at $45 on entry into IRQ interrupt
processing.

Restore 6502 Registers

The routine at label RESTORE is the inverse of the SAVE routine,
except that the S-reg is not loaded. In the Old Monitor, RESTORE is
utilized by instruction step and trace routines before controlled
execution of each traced instruction. In both Monitors, the registers
are loaded by RESTORE in execution of the Monitor G command before
transferring control to the operator-indicated location.

Multiply Two Byte Fields

The MUL and MULPM routines Multiply two byte fields to give a four
byte product. They exist only in the Old Monitor. If a program (such
as an assembler) calls MULPM at FB60, and it is executed with the
Autostart Monitor in the machine, the result is that on each call the
screen will be cleared and “APPLE II” will be written on the top line.

Multiply Routine

Note in the following that the data fields for multiply and divide are
in the same format as other multiple byte numbers in the Apple: lowest
memory address is least significant byte.

Set Multiplier in             $55,54 (MSB,LSB)
Set Multiplicand in           $51,50 (MSB,LSB)
Should be zero - see note     $53,52

Call/JSR FB60 or FB63 (-1184 or -1181) (MULPM or MUL) depending on
sign conventions or requirements.

The result, in order of most significant to least, is in $53, $52,
$51, $50. this result is positive. If one of the two input factors
(but not both) was negative, then SIGN (at $2F) contains an $01 bit,
indicating that the result should be complemented by the user program
before further use.

NOTE: The table of values above indicates that $53,52 should be set
to zero before calling multiply. If this is not done, then the initial
contents of this field will be added to the result. For example, if a
table has an origin of $8400 with 7 byte long entries, the address of
entry 8 can be determined by entering the multiply with $8400 in
$53,52 and the 8 and 7 in position for the multiply.

Examples :

     Called        Inputs              Outputs
     Routine    $51 $50  $55 $54     $53 $52  $51 $50  $2F
     _____________________________________________________
     MULPM       00  01   00  01      00  00   00  01   00
                 00  01   01  00      00  00   01  00   00
                 04  00   08  00      00  20   00  00   00
                 FC  00   08  00      00  20   00  00   01
                 FC  00   F8  00      00  20   00  00   02
                 7F  FF   7F  FF      3F  FF   00  01   00
                 80  00   02  00      01  00   00  00   01
                 80  00   80  00      40  00   00  00   02
     MUL         00  01   00  01      00  00   00  01
                 00  01   01  00      00  00   01  00
                 04  00   08  00      00  20   00  00
                 FC  00   08  00      07  E0   00  00
                 FC  00   F8  00      F4  20   00  00
                 00  FC   00  F8      00  00   F4  20
                 80  00   02  00      01  00   00  00
                 80  00   80  00      40  00   00  00
                 12  34   56  78      06  26   00  60

Divide Four Byte Dividend by Two Byte Divisor

This routine divides a four byte dividend by a two bit divisor, giving
a two byte quotient and a two byte remainder. It is available only in
the Old Monitor. This routine accomplishes the division of the number
in bytes $53,52,51,50 by the number in bytes $55,54, leaving the
quotient in $51,50 and the remainder in $53,52 (most significant to
least significant).

If the contents of $53,52 is larger than the contents of $55,54, then
the result will not fit in the quotient bytes - overflow is the
result. The calling program must not let this happen.

With regards to scaling, looking at the four byte dividend as an
integer value and the divisor in $55,54 as an integer, the quotient
and remainder fields are also integers.

Sign can be a problem if the DIVPM entry point is used. The sign bit
of the dividend is the $80 bit of byte $51. If the intended divide is
two bytes (with $53,52 cleared before divide) then signed fields
division is supported, with the sign bit being the LSB of $2F. If the
call is to DIVPM, and if $2F contains $01, then complement the results
before using them.

When using unsigned divide, entry point DIV, then the divide is 32 bit
field by 16 bit field with 16 bit results.

Examples:

     Called            Inputs                 Outputs
     Routine      Dividend   Divisor    Quotient  Remainder  Sign
     ______________________________________________________
              $53 52 51 50   $55 54     $51 50    $53 52     $2F
     ______________________________________________________
     DIVPM     00 40 00 00    08 00      08 00     00 00      00
     [$FB81]   00 00 00 08    00 04      00 02     00 00      00
     [64385]   00 01 00 00    00 02      80 00     00 00      00
     [-1151]   00 00 00 03    00 02      00 01     00 01      00
               00 00 30 00    02 00      00 18     00 00      00
               00 00 30 00    20 00      00 01     10 00      00
               00 00 33 33    00 22      01 81     00 11      00
               00 10 40 00    04 00      04 10     00 00      00
               00 20 80 00    08 00      04 10     00 00      01
                     __       __                              __
               00 20 82 00    08 00      04 0F     06 00      01
                     __       __                              __
               00 10 41 00    04 00      04 10     01 00      00

     DIV
     [$FB84]   00 80 00 00    80 00      01 00     00 00
     [64388]   00 00 80 00    08 00      00 10     00 00
     [-1148]

Establish a RESET Vector

The Autostart Monitor supports an address vector for completion of
handling a RESET interrupt. It is called the Soft Entry vector as it
is designed to allow resumption of processing after a RESET. This
vector is in page three. It contains the address to which control is
to be transferred after the screen, keyboard, and other basic Apple
hardware items have been set to their “initial” states. For example,
the display hardware is set to display primary area text, and the
Scroll Window full screen values are set.

After such initialization is performed, locations $03F3 and $03F4 are
tested against one another to determine whether the vector in $03F2-
$03F3 is to be considered valid. If so, control is transferred to
($03F2-03F3). Normally, this results in transfer of control to $E003
to accomplish the result of entry to the Monitor of a control-C, re-
entry into BASIC or APPLESOFT. During the bootstrap operation, DOS
installs its own restart point in this vector. And, of course, you may
wish to set some other value in this vector, such as that which will
cause the Monitor (with asterisk prompt) to be called, as was the
normal case with the Old Monitor. To set a different value in that
vector, POKE or store the desired value in $03F2-$03F3 and then CALL
or JSR to SETPWRC ($FB6F or -1169) to have the Monitor set $03F4
appropriately.

Convert Hex Characters to Value for Use

Programmer utility programs often need input of address or data in hex
rather than in decimal. The Monitor also uses input in hex, and
therefore has a way of converting input hex characters to a value in a
field. The GETNUM routine in the Monitor converts characters from the
keyboard input area ($0200-$02FF) to hex stored in A2L,H and
conditionally in AIL,H and A3L,H.

The GETNUM routine converts characters in the $0200 area beginning at
$0200+(Y-reg) and continuing until a character is found which is not a
hex digit (not 0-9 or A-F). The result in A2L,H (and AIL,H and A3L,H
if (MODE) = 0) is the last four hex digits in the string converted if
the string is more than four hex digits. If the string is fewer than
four hex digits the result field contains the value right adjusted
with leading zeroes. A sample program is provided at the end of this
section showing use of GETNUM from APPLESOFT.

Disassemble an Instruction

The Apple II Monitor contains a disassembler by means of which one can
display a portion of a machine language program in mnemonics instead
of just hex. At label LIST ($FE5E) is the routine to which control is
passed when the Monitor command “L” is used. This routine sets a
counter to 20, and then calls the single instruction disassembler 20
times, with appropriate adjustment of the instruction pointer PCL,H.
This routine can be used as an example of how to use the locations in
the address table with labels INSTDSP and PCADJ.

The routine at INSTDSP uses the INSDSl routine to set the zero page
locations FORMAT and LENGTH appropriately for the instruction at
(PCL,H). INSDSl also prints to the screen the contents of PCL,H, the
address of the instruction to be disassembled. On return from INSDSl,
the INSTDSP routine controls the printing of the rest of the
disassembly line.

Note that PCL,H is not altered by disassembly of the instruction,
Thus, it must be “maintained” by the program which calls INSTDSP.
This is accomplished by calling the PCADJ routine, which returns the
new values to the calling program, to store into PCL and PCH in the
A-reg and Y-reg, respectively, having computed the new value from PCL
and PCH and LENGTH (set by INSDSl).

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
OLD MONITOR ONLY
Multiply signed fields leaving       FB60  64352 -1184 MULPM    A,X,Y
 sign in LSB of SIGN.

Multiply fields unsigned,            FB63  64355 -1181 MUL      A,X,Y
 (51,50) * (55,54) = (53,52,51,50).

Divide signed fields leaving sign    FB81  64385 -1151 DIVPM    A,X,Y
 in SIGN LSB (from 51,55).

Divide unsigned fields               FB84  64388 -1148 DIV      A,X,Y
 (53,52,51,50)/(55,54)=(51,50).

Set absolute values for ACL,H and    FBA4  64420 -1116 MD1      A,X,Y
 AUXL,H leaving resulting sign in
 LSB of SIGN (called by MULPM and
 DIVPM).

-----------------------------------------------------------------------
AUTOSTART MONITOR ONLY
Set validity of RESET vector.        FB6F  64367 -1169 SETPWRC  A

-----------------------------------------------------------------------
BOTH OLD AND AUTOSTART MONITORS
Monitor Command Processor GO entry.  FEB6  65206 -330  GO       A,X,Y,P
 Set PCL,H from AlL,H if entered, &
 Call RESTORE, set all regs but S.&  FEB9  65209 -327
 Jump via PCL,H.                     FEBC  65212 -324

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Move bytes in memory to (A4L,H)      FE2C  65068 -468  MOVE     A
 from (AlL,H) thru (A2L,H).
 Note: Y-reg must be zero on entry.

Increment pointer A4L,H.           & FCB4  64692 -844  NXTA4    A
Increment pointer AlL,H with set     FCBA  64698 -838  NXTAl    A
 of carry if resulting (AlL,H) is
 greater than (A2L,H).

Save 6502 regs A,X,Y,P,S at
 $45-$49.                            FF4A  65354 -182  SAVE     A,X

Restore 6502 regs A,X,Y,P from       FF3F  65343 -193  RESTORE  A,X,Y,P
 $45-$48.

Convert hex characters from          FFA7  65447 -89   GETNUM   A,X,Y
 $200,Y to value in A2L,H (and
 AlL,H and A3L,H if (MODE)=0).

Disassemble one instruction with     F8D0  63696 -1840 INSTDSP  A,X,Y
 display thru COUT.

Compute new PCL,H after disassembly  F953  63827 -1709 PCADJ    A,X,Y
 or trace or step - return results
 in A,Y regs for (PCL,H).

APPLESOFT SAMPLE DATA MANIPULATION PROGRAM

10             REM  DATA MANIPULATION FUNCTIONS
20             REM   SAMPLE PROGRAM
30             REM  MEMORY DUMP
40             REM   OF HEX AREA INDICATED.
50     GOTO 1000:         REM  BYPASS SUBROUTINES
200            REM   CALL GETNUM ROUTINE VIA GO ROUTINE
210    POKE 58,167:       REM  PCL=$A7
220    POKE 59,255:       REM  PCH=$FF
230    SI$ = AD$ + “ “:   REM  BUILD STRING TO STORE
240    FOR I = 1 TO LEN (SI$)      REM:  STORE STRING IN INPUT BUFFER
250    CC$ = MID$ (SI$,I,l)        REM:               ‘’
260    CC% = ASC (CC$) + 128       REM:               ‘’
270    POKE 512 + I,CC%
280    NEXT
290    POKE 71,1:         REM  SET YREG TO START AT LOCATION 513
300    POKE 49,0:         REM  CLEAR MODE BYTE
310    CALL - 327:        REM  GO FROCESSOR
320    ST = PEEK (62) + 256 * PEEK (63):    REM  ST=START ADDRESS($A2)
330    IF ST > 32767 THEN ST = ST - 65536   REM  TWO’S COMPLEMENT
                                            ADDRESS IF >= $8000
340    RETURN
600           REM  DISPLAY HEX CONTENTS
610   SH% = ST / 256     REM GET HI ADDRESS BYTE
620   SL% = ST - SH% * 256:  REM  GET LO ADDRESS BYTE
630   IF SH% < 0 THEN SH% + 256:  REM  GET 2’S COMP IF NECESSARY
640   POKE 60,SL%:POKE 61,SH%
650   RM% = SL% - ( INT (SL% / 8 )) * 8  REM  RM% = MOD 8 OF LO BYTE
660   IF RM% THEN CALL -622
670   POKE 71,0:  REM  SET “Y” REG TO ZERO
680   POKE 58,163:   REM  PCL = $A3
690   POKE 59,253:   REM  PCH = $FD
700   CALL  -327:    REM  CLEAR “Y “ REG & $FDA3G
710   POKE 36,29:  PRINT “! “;:  REM   SEPARATES HEX FROM ASCII
720           REM  DISPLAY ASCII CHARACTER CONTENTS
730   SE = ST + 7 - RM%  REM  SEPARATES HEX FROM ASCII
740   FOR I = ST TO SE   REM  PRINT ASCII CONTENTS
750   CX = PEEK (I): IF CX < 128 THEN CX = CX + 128
760   CX$ = CHR$ (CX): IF CX < 160 THEN CX$ = “?”
770   PRINT CX$;
780   NEXT
790   RETURN
1000          REM PROGRAM START
1010  PRINT “HEX DISPLAY”
1020  INPUT “ENTER ADDRESS “ ;AD$
1030  IF AD$ = “END” THEN END
1040  IF LEN (AD$) = 0 THEN ll00:REM CONTINUE WITH NEXT AVAILABLE
                                     ADDRESS
1050  GOSUB 200:
1080  FOR J = 1 TO 16:  REM  PRINT 16 LINES
1090  GOSUB 600
1100  ST = ST + 8 - RM%
1110  NEXT
1120  PRINT
1130  GOTO l020

MONITOR COMMAND PROCESSOR

The Monitor Command Processor is that part of the Monitor which
responds to commands entered with the “*” prompt character. These
commands include data movement from one location to another, cassette
tape reading and writing, instruction disassembly, and others
described in the Reference Manual. The Reference Manual contains a
complete description of use of these commands. This section of this
manual describes calling some of the routines from a user program
instead of from the keyboard, and jumping into the Monitor with no
return to the user program.

ENTERING THE MONITOR COMMAND PROCESSOR

The Monitor Command Processor is that part of the Monitor which reads
keyboard input with the asterisk prompt character and performs the
requested service. “Entering” the Command Processor implies turning
over control of the machine to the Monitor Mode. When the RESET key is
pressed with the Old Monitor in the Apple the computer is placed in
Monitor Mode. When the RESET key is pressed with the Autostart Monitor
in the machine, the computer generally goes into BASIC or APPLESOFT.
With the Autostart Monitor the only way to get into Monitor Mode is to
CALL one of these entry points (generally CALL - 151).

In this mode, data may be moved in memory using the Monitor Move
command. Blocks can be read from tape via the cassette tape data
transfer commands. Or any of the other Monitor commands may be used.
However, having entered Monitor Mode, the Monitor Command Processor is
reading the commands from the keyboard and then acting upon them.

There are a number of entry points indicated in the address table for
“entering” the Monitor Command Processor. Please note that once the
Monitor is jumped to at the specified point, all of the initialization
described after that entry point is also performed. This is implied by
the “&” at the end of each function description.

CALLING THE MONITOR COMMAND PROCESSOR

“Calling” the Monitor Command Processor implies that return will take
place to the calling program. However, the driver part of the Monitor
Command Processor is not designed to operate in that fashion, so a
short machine language program is required to allow exit back to the
calling program. A sample program is provided at the end of this
section indicating the required setup. In the sample, the three byte
machine language routine is placed in page two (at $02FC) but it may
be placed anywhere desired. With this program, Monitor calls from
BASIC or APPLESOFT are both supported.

A program which CALLs the Command Processor must first store the three
byte exit routine somewhere. Then the program can POKE a string of
Monitor commands into the input area, beginning at address $0200, the
last command of each such string being a Monitor GO command to
transfer control to the exit routine. In the sample, the last Monitor
command in the string is “02FCG”. The function of the exit routine is
to pull one return address level (two bytes) off of the stack, and
then do an RTS to return to the BASIC, APPLESOFT, or machine language
calling program.

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Monitor Command Processor, “blank”   FE00  65024 -512 BL1      A,X,Y
 entry point used for CR.
Monitor Command Processor, “blank”   FE04  65028 -508 BLANK    A,X,Y
 command entry point.
Monitor Command Processor, Store     FE0B  65035 -501 STOR     A
 routine.
Monitor Command Processor, set       FE18  65048 -488 SETMODE  A,Y
 MODE for colon, period, plus, or
 minus.

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Store appropriate value to MODE,     FE1D  65053 -483 SETMDZ   none
 entered from BLANK also.
Monitor Command Processor routine    FE20  65056 -480 LT       A,X
 for less than (<) command.
Monitor Command Processor MOVE       FE2C  65068 -468 MOVE     A (Y=0)
 routine. (A1L,H) thru (A2L,H) is
 moved to (A4L,H) thru whatever.
Monitor command Processor VERIFY     FE36  65078 -458 VFY      A (Y=0)
 routine. (A1L,H) thru (A2L,H) is
 compared to (A4L,H) thru whatever
 with differences printed thru COUT.
Monitor Command Processor LIST       FE5E  65118 -418 LIST     A,X,Y
 (disassembler) routine: list 20
 instructions thru COUT.
Set INVFLG to $3F = inverse video.   FE80  65152 -384 SETINV   Y
Set INVFLG to $FF = normal video.    FE84  65156 -380 SETNORM  Y
Set INVFLG from Y-reg.               FE86  65158 -378 SETIFLG  none
Set port 0 (keyboard) for input.     FE89  65161 -375 SETKBD   A,X,Y
Set port (A) for input.              FE8B  65163 -373 INPORT   A,X,Y
Set port (A2L) for input.            FE8D  65165 -371 INPRT    A,X,Y
Set port 0 (screen) for output.      FE93  65171 -365 SETVID   A,X,Y
Set port (A) for output.             FE95  65173 -363 OUTPORT  A,X,Y
Set port (A2L) for output.           FE97  65175 -361 OUTPRT   A,X,Y
Monitor command Processor GO entry.  FEB6  65206 -330 GO       A,X,Y,P
 Set PCL,H from A1L,H if entered.  &
 Call RESTORE, set all regs but S. & FEB9  65209 -327
 Jump via PCL,H.                     FEBC  65212 -324
Monitor Command Processor Display    FEBF  65215 -321 REGZ
 Register contents.
Monitor Command Processor Carriage   FEF6  65270 -266 CRMON
 Return entry.
  First, simulate entry of blank.
  Then POP 2 from stack and goto
  Monitor Command Processor at MONZ.
Restore registers from $45-49:       FF3F  65343 -193 RESTORE
 Load STATUS and push to stack.    &
 Load A from ACC.                  & FF42  65346 -190
 Load X from XREG.                 & FF44  65348 -188 RESTR1
 Load Y from YREG.                 & FF46  65350 -186
 Load P from stack (PLP) and RTS.    FF48  65352 -184
Save 6502 regs at $45-49.            FF4A  65354 -182 SAVE
 Save A-reg at ACC $45.            &
 Save X-reg at XREG $46.           & FF4C  65356 -180 SAV1
 Save Y-reg at YREG $47.           & FF4E  65358 -178
 Save P-reg at STATUS $48.         & FF50  65360 -176
 Save S-reg at SPNT $49.           & FF54  65364 -172
 Clear 6502 decimal mode (set hex).

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
Monitor entry on RESET key pressed   FF59  65369 -167  RESET
 or Power on.
 Call SETNORM - white on black.    &
 Call INIT - Text + full scroll.   & FF5C  65372 -164
 Call SETVID  - screen as output.  & FF5F  65375 -161
 Call SETKBD  - keyboard = input.  & FF62  65378 -158
Clear 6502 decimal mode (set hex). & FF65  65381 -155  MON
Sound bell.                        & FF66  65382 -154
Monitor Command Processor Entry.     FF69  65385 -151  MONZ
 Set “*” as prompt character.      &
 Set (A) as prompt character.      & FF6B  65387 -149
Call GETLNZ to read command line.  & FF6D  65389 -147
Clear MODE before scanning line.   & FF70  65392 -144
Pick up one command:                 FF73  65395 -141  NXTITM
 Call GETNUM to scan input line,
  saving hex digits in A2L,H, and
  returning with non-hex in A-reg.
 Save Y at YSAV - current place in
  command line.
Call routine indicated by non-hex    FF82  65410 -126
 returned by GETNUM.
On return from Monitor Command       FF85  65413 -123
 Service routine, reload Y from
 YSAV and goto NXTITM to process
 next command in the line, if any.
Monitor Command Processor command    FFA7  65447 -89   GETNUM
 parsing routine; save hex digits
 in A2L,H, return with command
 (first non-hex) in A-reg, Y-reg
 set for next character.
Call routine indicated by command    FFBE  65470 -66   TOSUB
 character:
  Push address $FExx onto stack.
  Pass (MODE) to called routine in
   A-reg.
  Clear MODE before call.
  Call selected routine by RTS.
Clear MODE byte between commands.    FFC7  65479 -57   ZMODE

OLD MONITOR ONLY
Execute instruction at (PCL,H),      FA43  64067 -1469 STEP
 with display of instruction and
 result registers.
Monitor Command Processor TRACE      FEC2  65218 -318  TRACE
 instructions routine.
Monitor STEP one instruction.        FEC4  65220 -316  STEPZ
-----------------------------------------------------------------------
AlL,H  60,61  $3C,3D    PCL,H  58,59  $3A,3B
A2L,H  62,63  $3E,3F    ACC    69     $45
A3L,H  64,65  $40,41    XREG   70     $46
A4L,H  66,67  $42,43    YREG   71     $47
YSAV   52     $34

APPLESOFT SAMPLE PROGRAM
1           REM MONITOR COMMAND PROCESSOR SAMPLE PROGRAM
10 AA$ = “2FC:68 68 60 N 2FCG “: REM SET UP RETURN ROUTINE @2FC
11    GOSUB 1000:      REM MOVE COMMAND TO KEYBOARD INPUT AREA

100                  REM  RETURN IS SET. NOW CALL
101                  REM  SOME MONITOR COMMANDS.
110   AA$ = “F800L 100.1FF 2FCG “
120   CALL  - 936:   REM  CLEAR THE SCREEN
130   GOSUB 1000:    REM  DO DISASSEMBLY, MEMORY DISPLAY, RETURN
140   PRINT : PRINT :
141   PRINT “THATS ALL. “
150   END

1000  B = 511:  REM FOR LOOP IS 1 TO LIM, SO B=BYTE BEFORE $200
1005  LIM = LEN (AA$)
1010  FOR I = 1 TO LIM
1020  P$ = MID$ (AA$,I,l)
1050  P = ASC(P$) + 128
1070  POKE B + I,P
1080  NEXT
1085  CALL - 144
1090  RETURN

SPEAKER USE THROUGH THE MONITOR	
	
There are many ways to use the speaker in the Apple II. One of these
ways is to signal program events. The Monitor contains a routine which
supports this use by toggling the speaker at 1 khz for .1 second. This
is the “beep” heard when the RESET key is pressed or at completion of a
tape record read or write.

The Apple II does not contain the only speaker in town. That is, some
printers which attach to the Apple II make a sound of some type when
presented with the BELL code. On the Apple II keyboard this is the
control-G. The character code is $87 or decimal 135. “Printing” this
character through COUT will cause the Apple to beep, and will cause a
printer “bell” to sound if there is one.

There are two ways for a user program to call the routine in the
Monitor which responds to output of $87 by sounding the beep.

     If you intend to sound the bell in the Apple regardless of
     output device in use, then directly call the routine in the
     Monitor which produces the sound; CALL -1059 (or CALL 64477),
     or JSR FBDD expecting destruction of the A-reg and Y-reg.

     If you want to sound the bell of the Apple II if the screen is the
     print device, or to sound the speaker in the printer, call the
     entry point in the Monitor which places a $87 in the A-reg and
     “prints” it through COUT; CALL-198 (or CALL 65338) or JSR FF3A
     expecting destruction of the A-reg.

ADDRESS TABLE

Function                             Hex   +Dec  -Dec Monitor Registers
                                     Addr  Addr  Addr  Label  Destroyed
_______________________________________________________________________
If (A)=$87 wait .01 seconds, then    FED9  64473 -1063  BELL1    A,Y
 sound the “bell”. Else, RTS.
Wait .01 seconds, then sound bell.   FBDD  64477 -1059           A,Y
Load Y = 192 for .1 sec of bell,   & FBE2  64482 -1054           A,Y
Toggle speaker at 1 KHZ for number   FBE4  64484 -l052  BELL2    A,Y
 of cycles in Y-reg.
Print thru COUT “ERR” and bell code. FF2D  65325 -211   PRERR    A
Print bell code ($87) thru COUT.     FF3A  65338 -198   BELL     A

CASSETTE TAPE INPUT AND OUTPUT

There are two primary entry points in the Monitor with regard to
reading and writing tape. They are READ and WRITE. The requirements for
Calling these are described below. There are a number of other routine
entry points which are used by the Monitor on bit and byte basis. These
are described below to the extent of location in the Monitor and
indication of which Apple II programs call them but the precise
timings of instructions between consecutive calls is beyond the scope
of this manual.

As you will have found by now, some tape files are composed of one
record, and some of two records. For example, LOADing an APPLESOFT or
BASIC program results in two beeps, signaling the completions of the
reads of two separate records from the tape.

Definitions are in order:

    A tape record is a single contiguous string of bits which is read
    into or written from memory as a unit. A tape record is a
    physical entity.

    A file on tape is a series or sequence of one or more records
    containing data in a logical organization. A file is a logical
    entity.

An APPLESOFT or BASIC program file consists of two records. For BASIC,
the first of these records is two bytes long, and contains the length
of the second record. When the Monitor has satisfied BASIC’s read of
the first record, BASIC uses the record length indicated in that record
to determine the start and end points in memory into which the Monitor
will read the second record. Each call to READ or WRITE in the Monitor
accomplishes only one record input or output.

APPLESOFT programs are also SAVEd as two record sets or files. However,
the first record is three bytes long: the first two bytes indicate the
length, and the third byte is set to $55 to indicate a normal APPLESOFT
II (as differentiated from APPLESOFT I) program.

Some other programs write a longer (but fixed length) first record
containing length of the second record of the file, and other information
about the file such as date of creation or name of the file.

WRITE

$FECD  65229  -307

Before entry at this point, set the first byte address in AlL,H ($3C-
3D) and the last byte address at A2L,H ($3E-3F). The Monitor will write
ten seconds of continuous tone (header) followed by the contents of
memory as specified, followed by one byte of checksum (the result of
Exclusive OR of all the data bytes written to the tape).

READ

$FEFD  65277  -259

Before entry at this point, place the first byte address into AlL,H
($3C-3D) and the last byte address into A2L,H ($3E-3F). The Monitor
reads the data from the tape, storing it into memory in the specified
locations, and maintaining a running Exclusive OR result in the zero
page field called CHKSUM ($2E). When the last specified memory location
has been filled from the tape, the Monitor reads one more byte and
compares it with the contents of CHKSUM. If equal, the Monitor sounds a
beep and returns to the calling program. If not equal, the Monitor
prints “ERR” through COUT before sounding the beep and returning.

If you want to have the calling program determine whether the tape was
read successfully or not, then some special actions must be taken. One
method is to compare the contents of CH ($24) before the tape read with
the contents after. If they are equal, ERR was not printed to the
screen. If the cursor horizontal position (CH) has changed across the
call to READ, then ERR must have been written to the screen. If this
condition is encountered, the program can then ask the operator to
position the tape and signal the program for another attempt at reading
the record. Caution: If CSWL,H points to a printer card or other
routine which does not output to the screen, CH will not be incremented
by the output of “ERR”.

CASSETTE INPUT/OUTPUT INTERNAL ROUTINES

The following entry points/routines functions are described, but not
documented in sufficient detail for call by user program. For some of
them, timing is critical and the documentation for using them would
depend on how they were to be used.

HEADR

$FCC9  64713  -823

This routine writes the synchronization monotone which is the first
part of every tape record. When the WRITE routine calls HEADR, it loads
a $40 into the A-reg causing a 10 second header to be written. The READ
routine also calls HEADR to delay from first detection of data coming
in from the tape to the first point at which reading for 0/1 detection
begins. READ loads the A-reg with a $16 before calling HEADR so the
delay for hardware settling is set to about 3.5 seconds. This routine
is not called by BASIC or APPLESOFT, but it is used by the Programmer’s
Aid #1 Tape Verify routines which read the tape and compare the data to
memory instead of storing the data into memory.

RD2BIT

$FCFA  64762  -774

This routine causes looping with decrementing of the Y-reg until the
hardware has indicated two transitions of the tape input register. The
routine RDBIT is called twice for this purpose. Contents of the Y-reg
on return compared with contents on entry indicate the length of time
it took for the transitions.

This routine is called from within the Monitor by the READ routine, to
delay entering data transfer mode until tape input is available. READ
calls HEADR for the 3.5 second delay on return from its call to RD2BIT.
This routine is also called from APPLESOFT and from the Tape Verify and
Shape Table Load programs in the Programmer’s Aid #1.

RDBIT

$FCFD  64765  -771

This routine loops with decrementing of the Y-reg while testing the
tape input register for transition from zero to one or one to zero. Bit
value of zero or one is then determined from the residual count in the
Y-reg. This routine is called from within the Monitor routines RD2BIT
and READ. It is also called by Programmer’s Aid #1 Tape Verify.

RDBYTE

$FCEC  64748  -788

This routine calls RD2BIT as required in order to assemble a byte of
information from the tape. It then returns to caller with the byte in
the A-reg. In addition to being called from the Monitor READ routine,
it is also called by Shape Table Load in Programmer’s Aid #1.

WRBIT

$FCD6  64726  -810

This routine accomplishes writing a bit to the tape when called by
either the HEADR routine or the WRBYTE routine.

WRBYTE

$FEED  65261  -275

When called to write a byte to the tape, this routine uses WRBIT to
write ten bits to the tape. The only caller is WRITE in the Monitor.

PADDLES, BUTTONS & ANNUNCIATOR I/O
	
The Apple II has a Game I/O connector with hardware support for four
digital outputs, three digital inputs, and four analog inputs (called
paddles). The Monitor reads the paddles by writing a strobe to start
the paddle timer and then reading the selected paddle timer and
incrementing the Y-reg until that timer comes true. The result of the
read is in the Y-reg. Monitor support for digital outputs or digit
inputs is not required. Access to the digital I/O ports is gained by
PEEKing or POKEing the appropriate address, or by LDx or STx if
machine language is used. The Autostart Monitor does initialize the
digital output ports (annunciators) on any RESET key interrupt. AN0
and ANl are initialized to the clear (TTL LO) condition by reference
to addresses $C058 and $C05A. AN2 and AN3 are initialized to the set
(TTL HI) condition by reference to addresses $C05D and $C05F.

To use the Monitor support to read the setting of a paddle, JSR to

PREAD        FBlE    64286    -1250

with paddle number (0-3) in X-reg, and on return the “value” of the
paddle will be found in the Y-reg. The A-reg is destroyed in the
process. (APPLESOFT and BASIC support paddle reading, so setting of
and looking at Y is not required there.)

Direct reading of the paddles may be accomplished by accessing the
paddle trigger to start all paddle timers and then reading the
appropriate paddle input address repeatedly while counting until the
value read from the paddle address no longer has the $80 bit set.

CAUTION: After reading a paddle, let some time go by before reading
another paddle or incorrect results may be a problem. When the paddle
trigger is strobed, all the timers start. If the first paddle you
read has a low value, on going back quickly to read another paddle
the transition you see may be from the first paddle trigger instead
of the second. See the sample program in the section “Use of
Control-Y with Parameters”. Another solution is to do a read of a
fake paddle between real readings.

GAME I/O HARDWARE ADDRESS TABLE

Game I/O Hardware Address     Hex   +Dec   -Dec   Action/Comments
                              Addr  Addr   Addr
_____________________________________________________________________
Start Paddle Timers.          C070  49264  -16272

Paddle 0 timer.               C064  49252  -16284  Negative until
Paddle 1 timer.               C065  49253  -16283    timer
Paddle 2 timer.               C066  49254  -16282      expires.
Paddle 3 timer.               C067  49255  -16281

Paddle 0 switch.              C061  49249  -16287  Negative
Paddle 1 switch.              C062  49250  -16286   indicates
Paddle 2 switch.              C063  49251  -16285    button pushed.

Clear Annunciator 0 output.   C058  49240  -16296  POKE/STore
Set   Annunciator 0 output.   C059  49241  -16295   zero
Clear Annunciator 1 output.   C05A  49242  -16294    to
Set   Annunciator 1 output.   C05B  49243  -16293     appropriate
Clear Annunciator 2 output.   C05C  49244  -16292      address.
Set   Annunciator 2 output.   C05D  49245  -16291
Clear Annunciator 3 output.   C05E  49246  -16290
Set   Annunciator 3 output.   C05F  49247  -16289

WAIT ROUTINE
	
The WAIT routine consists of a loop within a loop, constructed in
such a manner that the length of time spent in the loop varies
geometrically with the entry A-reg. A call to this routine will cause
a loop for a predictable length of time, such as is used by the
Monitor with regards to using the speaker as a belL. It may be
usable, for example, in writing data to a lower speed device like a
printer or a typewriter.

WAIT            $FCA8   64680   -856

Anaylsis of the code indicates that the time between the call WAIT
(JSR) and the end of the RTS of WAIT is approximately
     2.5A**2 + 13.5A + 13 machine cycles of 1.023 microseconds.
where A equals the contents of the accumulator.

An alternative formula is
     TIME IN MICROSECONDS = (2.5 * (A^2) + 13.5 * A + MC) * MS
where A = contents of accumulator
     MC = 13 machine cycles
     MS = 1.023 microseconds

The following table indicates delay times in the WAIT routine for a
number of values of the A-reg on entry.

WAIT ROUTINE DELAY TIMES

  A-reg   Time in     A-reg   Time in       A-reg   Time in
  (Dec.)  seconds     (Dec.)  seconds       (Dec.)  seconds

  ----------------------------------------------------------
    1     .000029667   49     .006830571    137     .049907055
    2     .00005115    50     .007097574    138     .050624178
    3     .000077748
    4     .000109461   53     .007929273    150     .059628624
    5     .000146289   54     .008216736    151     .060412242
    6     .000188232   55     .008509314
    7     .00023529    56     .008807007    162     .06936963
    8     .000287463   57     .009109815    163     .070214628
    9     .000344751   58     .009417738
                       59     .009730776    174     .079847196
   17     .000987195   60     .010048929    175     .080753574
   18     .001090518
   19     .001198956   73     .014650383    184     .089141151
                       74     .015040146    185     .090098679
   25     .001956999   75     .015435024
   26     .002101242                        195     .099955284
                       85     .019665129    196     .100969077
   31     .002899182   86     .020116272
   32     .003074115                        204     .109263561
                       96     .024909027    205     .110323389
   36     .003824997   97     .025416435
   37     .004025505                        218     .124566618
                      105     .029659839    219     .125698056
   41     .004878687  106     .030213282
   42     .00510477                         239     .149400966
                      122     .03976401     240     .150639819
   45     .005813709  123     .040404408
   46     .006060252                        255     .169836414

USE OF CONTROL·Y WITH PARAMETERS	

In the APPLESOFT manual there is a caution that if one paddle is read
another should not be read too quickly. Following is a machine
language program with which the interference between the paddles can
be demonstrated.

Initiate this program by entering the Monitor command xxxxY, where
xxxx is a mimber representing the amount of delay to use between
reading paddle 0 and reading paddle 1, and Y represents control-Y.
The Monitor command “control-Y” causes a JMP to location $03F8 at
which location we place a JMP to the beginning of the program.

As the Monitor scans the input command line, the value of the hex
digits is placed in page zero locations AlL,H ($3C-3D) for our use.

PADDLE INTERFERENCE—SAMPLE PROGRAM

03F8  JMP  $2000

2000  LDA  $#C0    Set counter for 64 samples to run
2002  STA  $4       before clearing screen and starting over.
2004  LDA  $3C     Pick up low part of entered count from AlL
2006  STA  $10      and store it for repeated use.
2008  LDA  $3D     Pick up high part of entered count from AlH
200A  STA  $11      and store it for repeated use.

200C  LDA  $10     Pick up low part of count:
200E  STA  $12      store it in counter for this pass,
2010  LDA  $11      and also high part.
2012  STA  $13
2014  LDX  $#0     Set X for paddle 0 read.
2016  JSR  $FB1E   Call paddle read.
2019  STY  $0      Store paddle 0 result in location 0.

201B  DEC  $12     Count down delay loop low byte:
201D  BNE  $201B    when zero, count down high byte.
201F  DEC  $13
2021  BMI  $201B   Stay in the loop until high goes minus.

2023  LDX  $#1     Set X for paddle 1 read.
2025  JSR  $FB1E   Call paddle read.
2028  STY  $1      Store paddle 1 result in location 1.

202A  LDA  $0      Pick up paddle 0 value.
202C  JSR  $FDDA   Print it as a hex value.
202F  LDA  $#A0    Pick up a blank to print.
2031  JSR  $FDED   Print the blank.
2034  LDA  $1      Pick up paddle 1 value.
2036  JSR  $FDDA   Print it as a hex value.
2039  JSR  $F948   Print three blanks.

203C  INC  $5      Delay for awhile to keep paddle 1 read
203E  BNE  $203C    from up setting paddle 0 results.

2040  INC  $4      Is it time to clear screen and restart?
2042  BNE  $200C    NE means no, go back and sample again.

2044  LDA  $#0     Wait a while before clearing screen.
2046  STA  $4
2048  STA  $5

204A  INC  $4
204C  BNE  $204A
204E  INC  $5
2050  BNE  $204A
2052  JSR  $FC58   Clear the screen.
2055  LDA  $#C0    Restore the per screen counter,
2057  STA  $4
2059  BNE  $200C    and go one more big round.

REGISTERS FOR BASIC MONITOR CALLS
	
Many of the entry points specified in this book require presetting of
registers for proper operation. Following is a sample program,
written for APPLESOFT, which uses Monitor calls for conversion from
decimal to hex.

The theory behind the operation is that on a Monitor G command, the
registers are loaded from the SAVE area before going to the location
specified in PCL,H. Thus, by poking destination address into PCL,H
and the required register contents into XREG, YREG, an entry point in
the Monitor Go command processor can be used to pass the registers to
a selected routine.

DECIMAL TO HEX CONVERSION
	
APPLESOFT SAMPLE PROGRAM

10   REM CONVERT DECIMAL INPUT TO HEX OUTPUT
100  INPUT “ENTER NUMBER “;A    Read the input.
110  IF A=99999 THEN END        Provide a way to end the program.
150  C% = A / 256               Isolate the high byte.
200  POKE 71,C%                 Set YREG for PRNTYX call.
300  B% = A / 256               Get remainder from A/256.
310  B = B% * 256               For low byte (XREG) POKE.
320  B% = A - B
350  POKE 70,B%
400  POKE 59,249                Set PCH to $F9.
500  POKE 58,64                 Set PCL to $40.
550  PRINT                      Print a blank line.
600  CALL 65209                 Entry point in GO processor is FEB9.
650  PRINT                      Print a blank line.
700  GOTO l00                   Go around for another number.

STEP AND TRACE PECULIARITIES	

The Step and Trace functions in the Old Monitor incorrectly display
register contents under some circumstances. The STEP routine detects
and gives special attention to JSR, RTS, JMP, JMP indirect, RTI, and
BRK instructions. In each case, the register contents are displayed
from the SAVE area at $45-49. However, there is no SAVE call after
“execution” of these instructions, as there is for normally traced
Instructions, so the registers displayed are those present in the
SAVE area before execution of this instruction.

Therefore, on JSR and RTS, the displayed contents of the S-reg are
incorrect. On the first instruction after a JSR or RTS, the S-reg
displays correctly, unless that also is an RTS or JSR.

The Step and Trace routines are not incorrect in handling of a BRK
instruction. That is, the address displayed for the BRK is correct,
instead of being off by two bytes, because the BRK is detected by the
STEP routine instead of being executed by the 6502.

Although step and trace can be very helpful for some program
debugging tasks, they cannot be used in tracing calls to the Monitor
(generally including “print” output) or for programs which use AlL,H
thru A4L,H.

Because of the lack of “CLD” at PCADJ ($F953), incorrect addresses
will be displayed if you set decimal mode (SED) within the program
being traced or stepped.